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Chapter 1 



Introduction 



TSX-Plu8 is a high performance operating system for Digital Equipment Corporation PDP-11 and LSI-11 
computers, supporting as many as forty concurrent time-sharing users. TSX-Plus provides a multi-user 
programming environment that is similar to extended memory (XM) RT-11. 

• TSX-Plus keyboard commands are compatible with those of RT-11. 
TSX-Plus supports most RT-11 system service calls (EMTs). 



• 



• Most programs that run under RT-11 will run without modification under TSX-Plus. This includes 
RT-11 utility programs such as PIP, DUP, DIR, LINK, KED, BUP and MACRO. 

• TSX-Plus uses RT-11 XM version device handlers. 

• TSX-Plus provides PLAS extended memory services such as virtual overlays and virtual arrays, as 
well as support for extended memory regions. 

TSX-Plus can simultaneously support a wide variety of jobs and programming languages including COBOL- 
Plus, FORTRAN, BASIC, DIBOL, DBL, Pascal, C, MACRO, IND, TECO and KED. TSX-Plus is used in 
educational, business, scientific and industrial environments. It can concurrently support commercial users 
doing transaction processing, engineering users performing scientific processing, system programmers doing 
program development, and real-time process control. Numerous application software packages compatible 
with TSX-Plus are available from other vendors. 

TSX-Plus supports RT-11 system service calls (EMTs) as its basic mode of operation. The result is low 
system overhead and substantially improved performance over systems that emulate RT-11 services. TSX- 
Plus overlaps terminal interaction time, I/O wait time, and CPU execution time for all jobs on the system. 
The result is a tremendous increase in the productivity of the computer system. 

In addition to the basic RT-11 functionality, TSX-Plus provides extended features such as: process windows; 
shared file record locking; inter-job message communication; program performance monitoring; command file 
parameters; logon and usage accounting; directory and data caching; multitasking; and system I/O buffering. 

This manual describes all the features unique to TSX-Plus as well as any differences from RT-11. Many of 
the special features of TSX-Plus are available as EMTs available to the MACRO programmer. Access to 
these features from other languages requires the appropriate subroutine interface. 

TSX-Plus will run on any PDP-11 or LSI-11 computer with memory management hardware and at least 
256 Kb of memory, although additional memory may be needed for satisfactory multi-user performance. The 
system must also have a disk suitable for program swapping (the swapping disk can be used for regular file 
storage as well). Time-sharing lines and serial printers may be connected to the system through either single- 
line or multiplexer type interfaces. See the TSX-Plut Installation Guide for a list of interfaces supported for 
use with terminals and communications lines. Both hardwired and dial-up time-sharing lines are supported 
by TSX-Plus. 
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1.1 Management of System Resources 

1.1.1 Memory Management 

TSX-Plus uses the memory management facilities of PDP-11 computers to keep several user jobs in memory 
simultaneously and switch rapidly among them. TSX-Plus protects the system by preventing user jobs from 
halting the machine or storing outside their program regions. TSX-Plus provides several ways to control the 
amount of memory used by individual jobs. Programs may be allowed to use up to 64 Kb of memory and, if 
additional space is needed, may also use extended memory regions, virtual overlays and virtual arrays. The 
system manager may enable job swapping to accommodate more user jobs than can fit in existing memory. 

1.1.2 Execution Scheduling 

TSX-Plus provides fast response to interactive jobs but minimizes job swapping by use of the patented 
Adaptive Scheduling Algorithm. TSX-Plus permits job scheduling on both an absolute priority basis and by 
a method based on job states. For most applications, the method based on job states is preferred. The state 
driven method provides the most transparent time-sharing scheduling, suitable for interactive environments. 
The absolute priority method always runs the highest priority executable job, when not servicing interrupts, 
regardless of that job's state. This »tate free method is most suitable for an environment in which several 
real-time jobs must be assigned absolute priorities. TSX-Plus permits both kinds of jobs to co-exist in the 
same system, with interactive jobs being scheduled whenever higher priority state /ree jobs are not executing. 

Job priorities may be assigned over a range of to 127. The lowest priority jobs, typically to 19, are 
reserved for fixed priority jobs which can soak up system idle time without disturbing interactive or real- 
time jobs. The medium priority range, typically 20 to 79, is assigned to interactive jobs which are scheduled 
according to the Adaptive Scheduling Algorithm which makes time-sharing nearly transparent to several 
users. The highest priority range, typically 80 to 127, is reserved for jobs which must execute according to 
a rigid priority scheme such as might be found in a real-time environment. In addition, real-time jobs may 
execute interrupt service routines at fork level processing or schedule interrupt completion routines to run 
as fixed high priority jobs. 

Job scheduling is controlled by several system parameters relating job priorities, system timing and other 
events. The TSX-Plus System Manager's Guide includes a more complete description of job priority and 
scheduling. 

1.1.3 Subprocesses and Process Windowing 

TSX-Plus allows the time-sharing user to interact with and control multiple executing processes. The 
primary process for a user is invoked when the user logs on; subprocesses can easily be initiated by typing 
a control character digit sequence. The Process Windowing (tm) facility causes the system to monitor all 
characters sent to the terminal and maintain an in-memory image of what is currently presented on the 
terminal screen. This allows the system to restore the terminal display when switching between processes. 
Process Windowing also provides a print window function which, when invoked by typing a control character, 
causes the current window contents to be printed on a specified hardcopy printer or saved to a disk file. 

1.1.4 Directory and Data Caching 

TSX-Plus provides a mechanism to speed up directory operations by caching device directories. This reduces 
dbk I/O necessary to open existing files. Two methods of caching file data are also possible to further improve 
system throughput. When directory and generalized data caches are full, new data replaces least recently 
used existing data. When the shared file data cache is full, new data replaces least frequently used existing 
data. Directory and data caching are discussed in the TSX-Plus System Manager's Guide. 
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1.1.5 System Administrative Control 

TSX-Plus allows the system manager to limit access to the system through a logon facility and to restrict 
user access to peripheral devices. These features are described in the TSX-Plut System Managtr't Guide. 

1.1.6 Time-sharing lines and CL units 

TSX-Plus supports time-sharing terminal lines interfaced through several types of interface cards (see the 
TSX-Plue Inttallation Guide for a list of supported interface protocols). Using the CL feature provided with 
TSX-Plus, other serial devices such as printers, plotters and communications devices can also be attached 
using the same types of interfaces. Up to 16 CL units may be attached to TSX-Plus. (Units through 
7 are referenced as CLO through CL7 respectively; units 8 through 15 are referenced as CIO through C17 
respectively.) These devices may either be permanently assigned as CL units or may be used at some times 
as time-sharing lines and other times as I/O devices by having a CL unit take over an inactive time-sharing 
line. See the TSX-Plus User's Reference Manual description of the SET CL and SHOW CL commands for 
more information on using CL units. See the TSX-Plus Installation Guide for more information on including 
dedicated and extra CL units during system generation. 

1.2 Summary of Chapter Contents 

1.2.1 TSX-Plus Job Environment 

TSX-Plus supports the use of extended memory regions through EMT calls compatible with those provided 
by the RT-11 XM monitor. This allows the use of virtual overlays and FORTRAN virtual arrays. Users can 
also expand programs to use the full 16-bit virtual address space. That is, by giving up direct access to the 
I/O page and direct access to fixed offsets in RMON, a program may directly address a full 64 Kb. 

1.2.2 Program Controlled Terminal Options 

TSX-Plus allows the programmer to modify terminal handling characteristics during program execution. 
For example, a program may disable character echoing, use single character activation, use high efficiency 
output mode, enable lower case input, activate on field width, or dbable automatic echoing of line-feed after 
carriage-return. These terminal options may be selected either by issuing the appropriate EMT request or 
by writing a special sequence of two or three characters to the terminal. 

1.2.3 TSX-Plus EMTs 

TSX-Plus supports most of the system service calls (EMTs) provided by RT-11 and, in addition, provides 
many more to utilize the special features of TSX-Plus, For example, EMTs are provided to determine 
the TSX-Plus line number and the user name, to send messages to another time-sharing line, to check 
for terminal input errors, and to check for activation characters. EMTs related to specific features, such as 
detached jobs, inter-program messages or real-time programming, are described in the relevant chapters. The 
TSX-Plus EMTs which are not closely related to features described elsewhere are discussed in Chapter 4. 

1.2.4 Shared Files, Record Locking and Data Caching 

TSX-Plus provides a file sharing mechanism whereby several cooperating programs may coordinate their 
access to common data files. Programs may request different levels of shared file access, and control shared 
access on a block by block basis. Two methods of data caching are also provided: 1) generalized data caching 
which is enabled when devices are MOUNTed; and 2) record caching which is only available to shared 
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files. Directory caching is also enabled by the MOUNT request. This accelerates directory searching for file 
LOOKUPS. 

1.2.5 Inter-program Message Communication 

TSX-Plus offers a message communication facility that allows running programs to exchange messages. 
Messages are transmitted through named mctaage ehannclt. A program can queue messages on one or more 
message channels. Receiving programs can test for the presence of messages on a named channel and can 
suspend their execution until a message arrives. Receiving programs may also schedule a completion routine 
to be entered when a message arrives and continue other processing in the meanwhile. A message can be 
queued for a program that will run at a later time. 

1.2.6 Programming for CL and Special Device Handlers 

TSX-Plus provides a special serial communications line facility implemented as a device handler (CL), which 
may be used as a general purpose replacement for LS and XL (XC on the PRO). An interface port may 
be either defined as a time-sharing line or a communications port. Time-sharing lines may be later "taken 
over" as communications lines if the CL facility is included during system generation, either by a keyboard 
command or from within a program. Normal read/write functions may be used to CL units, but many 
special control features are available as special functions (.SPFUN requests). Certain other devices have 
special requirements or characteristics such as: DM, IB and VM. 

1.2.7 Real-time Support 

TSX-Plus provides real-time program support services that allow multiple real-time programs to run concur- 
rently with normal time-sharing operations. Real-time programs may optionally lock themselves in memory, 
directly access the I/O page, redefine their memory mapping, and connect device interrupts to subroutines 
within the program. 

1.2.8 Shared Run-time System Support 

TSX-Plus allows one or more shared run-time systems to be mapped into the address space of multiple TSX- 
Plus time-sharing jobs. This saves memory space when multiple users are running the same types of programs 
(e.g., COBOL-Plus or DBL) and can also be used in situations where programs wish to communicate through 
a shared data region. 

1.2.9 Program Debugging Facility 

TSX-Plus includes a symbolic (MACRO instructions) debugger with ODT styled commands. Debugger 
support is optionally included depending on a system generation parameter. The debugger need not be 
linked with the program being debugged and does not decrease the virtual memory space available to 
programs. The debugger may be invoked as part of the RUN command, with a BPT instruction from within 
the program or with a special keyboard control character. 

1.2.10 Program Performance Monitor Facility 

TSX-Plus includes a performance analysis facility that can be used to monitor the execution of a program and 
determine what percentage of the run time is spent within certain program regions. When the performance 
monitor is being used, TSX-Plus examines the program being monitored at each clock tick (50 or 60 times 
per second) and notes the value of the program counter. On completion of the analysis, the TSX-Plus 
performance reporting program can produce a histogram of the time spent in various parts of the monitored 
program. 
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1.2.11 Differences from RT-11 

Some inevitable differences exist between RT-11 and TSX-Plus. The TSX-Plus liter's Reference Mariual 
describes the additional keyboard commands provided by TSX-Plus, the minor differences in some com- 
mands, and the RT-11 keyboard commands not supported by TSX-Plus. Some other differences between 
RT-11 and TSX-Plus may not be obvious. The FORMAT utility is not supported. A few system ser- 
vice calls (EMTs) behave slightly differently in the two systems and some RT-11 EMTs are not supported 
by TSX-Plus (notably those supporting multi-terminal operations). A section is also included on special 
use and programming characteristics of some utility programs which may cause confusion because of some 
non-obvious interaction of their features with TSX-Plus. 

1.2.12 Appendices 

Appendix A describes the SETSIZ utility program which may be used to control the amount of memory 
available to programs. 

Appendix B provides a table of EMT function and subfunction codes, and brief descriptions of both RT-11 
and TSX-Plus EMTs; these are useful in conjunction with the SET EMT TRACE command. 

Appendix C contains listings of common subroutines called by the example programs throughout this 
manual. 

Appendix D describes a library of subroutines which are available to the DIBOL user to take advantage 
of some of the special features of TSX-Plus. 
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Chapter 2 

TSX— Plus Job Environment 



2.1 Simulated RMON 

While TSX-Plus implements the system monitor differently than RT-11, it does simulate relevant RMON 
fixed-offset locations. (See the section below on user virtual address mapping.) TSX-Plus defines certain 
special negative offset values for use with .GVAL (they cannot be obtained by reading relative to the simulated 
base of RMON). These special negative offsets are described in Chapter 4. Some notable features of the 
simulation of offsets defined by RT-11 are described in the following table: 



Offset 



Interpretation 



276 
366 

872 



This word is copied from RT-11 during TSX-Plus initialization and indicates the 

version and release level of RT-11. 

If the program is being run from a command file, then bits 8, 12, and 15 will be set 

in this word (mask 110400). 

If the program is not being run from a command file, then this word will be clear 

(0). 

Bit 15 (meisk 100000) is always set in this word by TSX-Plus; it is always clear 
under RT-11 



2.2 Virtual and physical memory 



The memory space that is accessible by a job is known as the virtual address space for the job. Because of 
the ai'chitectural design of the PDP-11 computer which uses 16 bits to represent a virtual memory address, 
the maximum amount of virtual address space that can be accessed at one time by a job is limited to 65,536 
(64 Kb) bytes. Thus, the virtual addresses for a job range from 000000 to 177777 (octal). 

The actual amount of virtual address space available to a job may be as large as 64 Kb but it may be restricted 
to less than this amount. The following factors control the size of the virtual address space available to a 
job: 

• The maximum amount of memory allowed for each job as determined by the HIMEM system generation 
parameter. 

• The amount of memory specified with the MEMORY keyboard command (initialized by the DFLMEM 
system generation parameter). 

• The memory limit reserved in the disk file image by the SETSIZ program (see Appendix A). 

7 
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• The amount of memory acquired by use of the TSX-Plus EMT that expands or contracts the job 
space. 

The physical address space for a PDP-11 computer is not limited to 64 Kb. The maximum physical address 
space depends on the model of PDP-11 and the amount of memory installed on the computer. LSI-ll/23 
and 11/34 computers can access up to 256 Kb of physical memory. The Il/2S-Plu8, 11/73, 11/24 and 11/44 
computers can access up to 4 Mb of memory. 

The process by which an address in the job's virtual address space is transformed into an address in the 
physical address space b known as mapping. The mapping of the virtual address space for a job into the 
physical memory space assigned to the job is performed by the memory management hardware facility of 
the PDP-11 computer. This facility divides the virtual address space into eight sections, called pages, each 
of which can address up to 8 Kb of memory. The mapping of a page of virtual address space to a page of 
physical address space is accomplished by setting up information in a page address register (PAR). There 
is one page address register for each of the eight virtual address pages. These registers are not directly 
accessible by a user job but are loaded by the TSX-Plus system when it starts a program, changes the size 
of a program, or switches execution between different jobs. The relationship between the eight pages of 
memory and the corresponding sections of virtual address is shown in the following table: 



Page 


Virtual address range 





000000-017777 


1 


020000-037777 


2 


040000-057777 


8 


060000-077777 


4 


100000-117777 


5 


120000-137777 


6 


140000-157777 


7 


160000-177777 



Because of the design of the memory management system in the PDP-11, it is not possible to divide the 
virtual address space more finely than eight pages of 8 Kb each. However, it is possible to map each page of 
virtual address space into any section of physical memory. (This facility allows TSX-Plus to keep multiple 
user jobs in physical memory and to switch rapidly among them by reloading the page address registers.) 



2.3 User virtual address mapping 

The virtual address space accessed by a job can be divided into five categories: 

• Normal program space — which is used by instructions and data for programs. 

• Simulated RMON— This is the virtual address region from 160000 to 177777 that is mapped to a 
simulated RMON (RT-11 resident monitor). 

• Extended memory regions — Programs can create regions in physical memory and then cause one or 
more pages of virtual address space to be mapped to the regions. 

• Shared run-time systems — Several TSX-Plus jobs can cause a portion of their virtual address space 
to be mapped to the same area of physical memory. This allows several users to execute the same 
program or share common data without having to allocate a separate area of physicaJ memory for each 
user. 

• System I/O page — TSX-Plus real-time programs may map the system I/O page into their virtual 
address space. 

These categories of virtual address space axe discussed in the sections below. 
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2.4 Normal programs and virtual programs 

Programs run under TSX-Plus may be divided into two categories: normal programt and virtual programs . 
The only difference between the two types of programs is the manner in which TSX-Plus handles page 7 
{addresses 160000-177777) of the virtual address space. In the case of normal programs, page 7 is mapped to 
a simulated RMON. RMON is the name of the resident RT-11 monitor. When running under RT-11 this is 
the actual system control program. When running under TSX-Plus, the simulated RMON does not contain 
any oiF the instructions that are part of RT-11 but contains only a table that provides information about the 
system and the job. This information includes such items as the system version number, and information 
about the hardware configuration. The cells in this table are known as RMON fixtd offsttt. Their position 
within the table and their contents are documented in the RT-11 Software Support Manual^ although not 
all cells are relevant to or maintained by TSX-Plus. 

The address of the base of the simulated RMON table is stored in location 54 of the job's virtual address 
space, Modern RT-11 and TSX-Plus programs should not directly access the RMON table but rather should 
use the .GVAL EMT to obtain values from the table. However, since some older programs and some RT-11 
utility programs directly access the RMON tables, it is mapped through page 7 for normal programs. As a 
result, normal programs are restricted to using pages to 6 (56 Kb) for their own instructions and data. 

Note fchat when simulated RMON is mapped into the job's virtual address space, it is mapped with read/write 
access. This makes it possible to corrupt data in the simulated RMON which should only be managed by 
the system. If a job does corrupt data in the simulated RMON cells, then it is possible for the job to receive 
erroneous error messages or to hang until the system is restarted. 

Virtual programs are programs that do not require direct access to the simulated RMON table. These 
programs may still access the RMON values with the .GVAL and .PVAL EMTs. Since direct access to the 
simulated RMON is not needed, page 7 is available for the program to use for its own instructions and data, 
thus providing a total of 64 Kb of virtual address space. A program may indicate that it is a virtual program 
by any of the following techniques: 

• Set bit 10 (VIRT$— mask 2000) in the Job Status Word (location 44) of the S AV file. See Appendix A 
for information about how this bit can be set by use of the SETSIZ program. 

• Use the /V LINK switch (/XM switch for the LINK keyboard command) which stores the RAD50 
value for VIR in location of the SAV file. 

• Use the TSX-Plus SETSIZ program (see Appendix A) and indicate that more than 56 Kb of memory 
is to be used for the program. 



2.5 Access to system I/O page 

The eyetem I/O page is an 8 Kb section of addresses which is not connected with ordinary memory but 
rather is used to control peripheral devices and hardware operation. Access to the I/O page is risky in that 
a program can interfere with peripheral devices and cause system crashes. For this reason, programs do not 
ordinarily have access to the I/O page. However, a program that is running with MEMMAP privilege may 
issue a system service call to cause page 7 (160000-177777) of the job's virtual address space to be mapped 
to the system I/O page. See Chapter 8 for more information on real-time programs. 

2.6 Job priorities 

TSX-Plus jobs may be assigned execution priorities to control their scheduling relative to other jobs. The 
priority values range from to 127. The priority values are arranged in three groups: 
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• The fixed-low-priority group consists of priority values from up to the value specified by the PRILOW 
sysgen parameter. 

• The fixed-high-priority group ranges from the value specified for the PRIHI sysgen parameter up to 
127. 

• The middle priority group ranges from (PRILOW-l-1) to (PRIHI-1). 

Job scheduling is performed differently for jobs in each category. Jobs in the fixed-high-priority range 
are scheduled strictly according to their priority and execute before any other job with lower priorities, 
including all interactive and fixed-low-priority jobs. Jobs in the interactive range are scheduled according 
to a patented algorithm which gives precedence to terminal operations. Jobs in the fixed-low-priority range 
are also scheduled strictly according to priority, but execute only when no other jobs of higher priority are 
executable, including all fixed-high-priority and interactive jobs. 

Job priorities may be influenced by the SET PRIORITY and SET PROCESS/PRIORITY commands (see 
the TSX-Plut Utcr't Reference Manual). Limits may be set on job priorities by the TSAUTH program and 
the SET MAXPRIORITY command (see the TSX-Plue System Manager's Guide), An executing program 
may also influence its own priority (see EMT 875, function 0,150 in Chapter 4). The current priority for 
a job and the maximum authorized priority can be displayed by use of the SHOW PRIORITY keyboard 
command, and may be obtained from within programs with the .GVAL request. 

See the description of EMT 575 function 0,150 in Chapter 4 and the TSX-Plus System Manager's Guide for 
more detailed discussions of job priorities and their eff'ect on job execution. 

2.7 Extended memory (PLAS) regions 

Programs running under TSX-Plus have available the Programmed Logical Address Space (PLAS) facility 
that is compatible with the RT-llXM monitor. This facility allows a program to allocate regions of physical 
memory and then create virtual windows that can be used to access the regions. There are 7 system service 
calls (EMTs) provided for PLAS support: 



EMT 


Meaning 


.CRRG 


Create a region 




.ELRG 


Eliminate a region 




.CRAW 


Create a virtual address window 




.ELAW 


Eliminate a virtual address window 




.MAP 


Map a virtual window to a region 




.UNMAP 


Unmap a virtual window 




.GMCX 


Get information about the status of a window 



A region is an area of physical memory set aside for use by a job in addition to its normal job space. The 
.CRRG EMT is used by a program to request that a region be created. The size of a region is not restricted 
to 64 Kb and may be as large as the physical memory installed on the system (less the space used by the 
TSX-Plus system, device handlers, tables, and the remainder of the program). Up to eight unnamed regions 
may be created by each job. 

PLAS memory regions can be grouped into two main categories: named regions and unnamed regions. 
Unnamed PLAS regions can only be accessed by the job that created them and only remain in existence as 
long at the job that created them is running. They are always deleted when the job exits or chains. Named 
PLAS regions may be shared between multiple jobs. Use of named PLAS regions requires SYSGBL privilege. 
Unlike unnamed PLAS regions, named regions are not necessarily deallocated when the program which 
created the region terminates execution. Named regions may be used to communicate between programs, 
to hold common code executed by multiple users (e.g., shared run-times), and to pass information from one 
program to another program — possibly run at a later time. 
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In addition to supporting named global PLAS regions in a fashion compatible with RT-11, TSX-Plus also 
provides an additional facility known os heal named regions . Local named regions are regions which can 
only be accessed by the job that created them. Their names are private to the creating job and more than 
one job may create (different) local regions with the same name. Local named regions are deallocated when 
the creating job specifies that they are to be eliminated or when the creating job logs oflF. 

Local named regions are allocated memory space associated with the creating job and are swapped in and 
out of memory with the job (like unnamed regions). Global named regions are allocated memory space at 
the top of the area of memory used for jobs. They are never swapped out of memory and are only deallocated 
when a job eliminates the region. Thus global named regions may continue to occupy memory after the job 
that created the region logs off. Caution should be exercised when creating global regions since it is possible 
to lock jobs out of memory by creating large global regions. 

Local named regions are distinguished from global named regions at creation time by setting bit (mask 
000001) in the status word (the third word — R.GSTS) of the region definition block used with the .CRRG 
EMT, 

Suimmary of Characteristics for Extended Memory (PLAS) Region Types 



Region Type 


Max lifetime of region 


Accessible by 
other jobs? 


Swapped out of 
memory with job? 


Unnamed 
Named local 
Named global 


Until program exits 
Until job logs off 
Indefinite 


No 

No 

Selectable 


Yes 
Yes 

No 



A SHOW REGIONS keyboard command may be used to display information about local and global named 
regions accessible by the job. 

The REMOVE keyboard command may be used to eliminate a local or global named region. The form of 
this command is: 



REMOVE region 

In order to access a region, a program must use the .CRAW and .MAP EMTs to create a virtual window and 
map the virtual window to a selected portion of the region. A virtual window is a section of virtual address 
space mapped to a region rather than to the normal job physical address space. Up to eight virtual address 
windows can be created by each job. The same virtual window (i.e., the same range of virtual addresses) 
may be mapped to different regions or different sections of the same region at different times by use of 
the .MAP EMT. This allows a program to selectively access different sections of code or data in extended 
memory regions during the course of its execution. 

Note that RT-11 allows a .CRAW and .MAP with a region ID equal to zero. TSX-Plus requires that 
the window definition block specified by the .MAP EMT contain a non-zero region ID returned from the 
successful creation of a region by use of the .CRRG EMT. TSX-Plus will return an error code 2 on the 
.MAF* EMT when a zero region ID is specified. 

When an unnamed or named local PLAS memory region is created by use of the .CRRG EMT, space is 
allocated in physical memory and in a TSX-Plus region swap file. Whenever a job is swapped out of memory, 
its extended memory regions are swapped to the region swap file. Space in the region swap file is allocated 
and deallocated dynamically as regions are created and eliminated. In order to create a region, space must 
be available in physical memory and in the region swap file. 

The PLAS facility is most often used implicitly through the virtual overlay and virtual array features. Using 
the PLAS facilities, it is possible for a single job to use all of the physical memory space available on a 
system (exclusive of the space used by the TSX-Plus system, handlers, tables, etc.). Proper use of the 
PLAS facilities such as with reasonable size virtual overlays or arrays can lead to substantial performance 
improvements for programs. Excessive use of memory space with the PLAS facility can lead to excessive job 
swapping and degraded system performance. 
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2.8 Shared run-time systems 

A shared run-time system is a program or data area in physical memory that can be accessed by multiple 
TSX-Plus jobs. Shared run-time systems are somewhat similar to extended memory regions in that they are 
both allocated in extended memory areas and must be accessed by mapping a portion of the job's virtual 
address space to the physical memory area. The difference is that extended memory regions are private 
to the job that creates them and may not be accessed by any other job. Shared run-time systems can be 
simultaneously accessed (hence "shared" ) by any number of TSX-Plus jobs. Another difference between 
regions and shared run-time systems is that regions can be created dynamically and can be swapped out of 
memory; shared run-time systems are specified when the system is generated and reside in memory as long 
as the system is running. See Chapter 9 for more information on shared run-time systems. 

2.9 VM pseudo-device handler 

While the VM handler is not actually mapped into a job's memory space, its use can dramatically increase 
job performance. The VM handler enables the use of a portion of physical memory as a pseudo-disk device. 
This permits very rapid access to programs and data which are placed on the VM unit. For programs such 
as compilers which heavily utilize overlay segments, a considerable speedup can be achieved by loading them 
onto the VM device. A similar improvement for overlaid programs can be obtained with the general data 
cache facility. However, when the data cache is full the least recently used blocks are lost. The presence 
of particular programs and their overlay segments in memory can be guaranteed by copying them to the 
VM pseudo-device. Another example of the usefulness of the VM device is with compilers which heavily 
use temporeuy work files. Depending on the number of write operations, which are not helped by general 
data caching, significant improvements in speed can be obtained by directing the work files to the VM 
pseudo-device. 

In order to use the VM device, it must be included in the device definitions during TSX-Plus system 
generation. An upper limit must also be placed on the amount of memory available to TSX-Plus. The 
physical memory above that available to TSX-Plus can then be used as a memory based pseudo-disk. If 
for some reason, it is desirable to use less than all of the memory above the top of TSX-Plus, the SET VM 
BASE command can be used to restrict the memory available to VM. Each time TSX-Plus is restarted, VM 
must be initialised just as you would for a new physical disk or a fresh logical subset disk. For example: 

INITIALIZE VM: 

Only one unit (VMO:) is available. However, logical subset disks may be created within the VM pseudo- 
device to partition it if necessary. On initialization, the VM handler automatically determines the amount 
of memory available to it. 

See the TSX-Plus System Manager's Guide for more information on the use of data caching (general and 
shared files) and the VM pseudo-disk. See Chapter 7 for descriptions of the special function requests 
supported by VM. 

2.10 User command interface 

TSX-Plus provides a method of intercepting and preprocessing user typed commands. This is called the 
"User Command Interface (UCI)". This may be implemented by writing a program to handle user input and 
enabling the facility with the SET KMON UCI command. After UCI is enabled, the TSX-Plus keyboard 
monitor will run the user-written UCI program each time it needs a new command. The program must 
prompt the user for a new command, accept the command, process it as desired and may optionally pass 
the command to the TSX-Plus keyboard monitor by doing a special chain exit. A special chain exit is 
performed by issuing the .EXIT request with bit 5 (mask 40) set in the job status word and with RO cleared. 
Any commands to be executed by the keyboard monitor are passed through the chain data area. See the 
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RT-11 Programmer's Reference Manual for more information on special chain exits. Commands passed to 
the TSX-Plus keyboard monitor in this fashion behave as though the keyboard monitor obtained them from 
a command file. A command file name may also be passed to the keyboard monitor by passing a command 
of the form "©name". If a command file name is passed to the keyboard monitor, then it must be the last 
or only command passed in the chain data area. When a command file name is passed in this manner, then 
all of the commands included in the command file are executed by the keyboard monitor before returning 
to the user-written UCI program for another command. 

The following program provides a simple example of the techniques for writing a User Command Interface 
progr8i,m. This program accepts a command from the keyboard and passes it through to the TSX-Plus 
keyboard monitor if it is a legal command. 

Exairiple 



; Slapl 

; paaii 

JSV 

SPXITt 

NONPTB. 

SYSGEN 

BEL 

BS 

LF 

FF 

Ct 

KSC 

START : 



.TITLE MYIMON 

.ENABL LC 

• txajipla of Usar Co>mand Interfaca 

at to pais SET INON SYSTEM, but otharvlta doai nothing but 

eomanda thru to KMDN. 



II: 



2$: 



QUIT: 

NATCH: 
1$: 



2$; 



.MCALL 
« 44 

' 40 

' 54 

» 372 

» 7 

» 10 

' 12 

* 14 

= 16 

» 33 

.DSABL 

.SCCA 

NOV 

1ST 

BPL 

NOV 

EMT 

ASL 

CMP 

BLOS 

CLE 

NOV 

.PRINT 

.PRINT 

NOV 

EMT 

.PRINT 

.GTLIN 

CALL 

BCS 

NOV 

CALL 

BIS 

CLE 

.EXIT 



NOV 

NOV 

TSTB 

BEQ 

CNPB 

BNE 

CMP 

BLO 

SEC 



.PRINT, .EXIT, .GTLIN, .SCCA 

;Job itatua 



GEL 

»AREA,«TTSTAT 

««MONPTR,10 

SYSGEN (RO) 

QUIT 

#TTYPE,RO 

S7B 

RO 

R0,«4 

1$ 

RO 

RO.Rl 

CLRSCR(Rl) 

*KENU 

*SETRUB,RO 

S7B 

CENTER (Rl) 

«BUFFER,iPRaNPT 

NATCH 

2$ 

#1000, SP 

NOVCMD 

«SPXIT$,««JSV 

RO 



«BUFFER,R2 

«ILLCND,RS 

(R2) 

21 

(R2)+,(R3)+ 

0( 

R3,»ILLEND 

1$ 



word addreat 
;Special axLt flag to paaa coamand to INON 
:Polntar to baaa of RNON 
: Off sat Into RNON of SYSGEN optiona vord 
:ASCII ball 
;ASCII backapaea 
; ASCII Una faad 
;ASCII fora faad 
; ASCII carrlaga raturn 
; ASCII aacapa 

;Diaabla undaflnad globala 
; Inhibit control-C abort 
;Get polntar to baaa of RNON 
;Ara va running undar TSXT 
; Normal axit If not 
;Point to ENT arg block to 
;Gat TSX-Plua tarminal typa 
jConrart to vord offaat 
;Lagal typaa ara unknown, VTE2 and VTIOO 

If not VT&2 or VTIOO, aaka unknown 

Sava tarminal typa 

Claar tha acraan 

Diaplay almpla manu 

Point to ENT arg block to 

Sat rubout fillar charactar 

NoTo to acraan eantar and claar tha lint 

Accapt input Una 

Sea if it la lagal 

Rapaat if illagal command 

Enaura atack polntar aafa 

Nova command from buffar to chain data an 

Sat apaclal chain «xlt bit in JSV 

Required for apaclal chain axlt 

And paaa command to INON 

Simple matching. Eaay to defeat by 

Inaertlng extra apacaa!!! 
Point to beginning of input buffer 
Point to beginning of Illegal command 
At end of Input atrlngT 
Yea, matched ao far, probably illegal 
No, teat through end of illegal atring 
No match, not illegal command 
Paat end of Illegal command? 
No, keep checking 
Stringa match, aignal illegal command 
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Bl 


9$: 


CLC 


10$: 


lETinLN 



10$ 



; strings do not Batch, signal lagal eosmand 



;NoTa conand from input buffar to chain data araa. 



NOVC^(D; 
It: 

31: 
St: 

Bt: 



AlEA: 
TI8TAT: 
ITYPE: 
8ETIUB : 



CLISCI: 
CENTEI: 

CLIUNI: 
CLlEa : 
CLllOO: 
CKTUNI: 
CNIE2: 



CNTIOO: 



MENU: 
PiOKPT: 



ILLCND 
ILLEND 
BUFFEl 
BUFEND 



NOV 

NOV 

NOYB 

BNB 

CLtB 

Bl 

CKPB 

BNE 

CLIB 

NOVB 

CNP 

BLO 

CLIB 

SUB 

NOV 

lETUlM 

.BLEW 

.WOiD 

.BTTE 

.BTTB 

.ffOlS 

.¥OiD 

.VOID 

.VOID 

.NLI8T 

.BYTE 

.BTTE 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.NLIST 

.EEPT 

.BYTE 

.ENDl 

.LIST 

.BYTE 

.ASCII 

.BLKB 

.END 



«B17FFE&,12 ; Point to beginning of Input atrlng 

•612, &S :Palnt to chain data araa 

(I2)'»,I0 ;Gat ntxt char 

2t :Continoa If not nul 

(tS)-» ;If and of input eoaaand 

9$ ; than dona 

10,i'\ ;Couand separatorT 

St :N0, BOTO it 

10 ;Yas, raplaca vith nul 

10,(13)-*^ ;NoTa coaaand into chain data araa 

12,«BnFEND :Do not vant to OTorflov 

1$ ;Koap BOTing if charactsrs laft 

-K&S) :Nark and of coamand (anaura it is A8CIZ) 

*B12,R3 :Hov Banj bytas did va botoT 

IS,C»E10 :Nark tha nuabar for .CHAIN 

10 ;GP ENT arguaant araa 

;Toralnal status word for .8CCA 

0,137 :ENT arg block to gat tarainal typa 

0,162 :ENT arg block to control tarainal funtiona 

'A sFunction coda - sat rubout fillar 

' :&ubout fillar ' ondarlina 



CLIUNI, CL&62.CLI100 

CNTUKI,CNT62, CNTIOO 

BEX 

rr,FF,FF.CI,200 

ESC, 'H, ESC, 'J, 200 

<E8C>/ [H/<ESC>/ [J/<200> 

<CE><LF><LF><LF>/ 

<ESC>/YX / 

<ESC>/I/ 

/ /<200> 

<ESC>/[6;6f/ 

<BSC>/[2I/<200> 

<LF><LF><LF>/ 

<BEL>/Coaaand: 



{Tarainal spaclfic scraan daars 
{Tarainal spaclfic aora and daar 

Eaulata claar scraan with S*(8LFs) 
VT52 claar scraan saquanca 
VTIOO claar scraan saquanca 
/<200> 

;Lina 6, celuan 1 

{Eras a to and of Una 

;NoTa to coluan 6 

;Llna 6, coluan 6 

{Erasa antlra Una 
••*** Siapla Nanu «****/<200> 



./ 



S2. 
BS 



<200> 

/SET INON SYSTEM/ 

81. 

8TAET 



{Backspaca to baglnnlng of flald 



;End of string 

;Do not parait DCI dlsabla 

{Coaaand Una input buffar 



Chapter 3 

Program Controlled Terminal 
Options 

3.1 Terminal input /output handling 

The terminal keyboard and screen provide the principal interface between a time-sharing user and the TSX- 
Plus operating system. TSX-Plus accepts characters from the keyboard, echoes them to the screen, and 
stores them in a separate buffer for each time-sharing user. When a program (either a user written program, 
a utility, or the operating system keyboard monitor) requests input from the terminal, characters are removed 
from the internal buffer and passed to the program. 

3.1.1 Activation characters 

The low-level requests for input from a program can call for a single character (.TTYIN), for an entire line 
(.GTLIN, .CSIGEN, .CSISPC), or for a whole block of characters (.READ). Since the requests for a whole 
line of input are most common, TSX-Plus improves overall efficiency for many users by retaining characters 
typed at the keyboard in an internal buffer until a special character is typed which indicates that the line of 
input is complete. This special character, which indicates that keyboard input is ready, is called an activation 
character. The standard activation characters are carriage return and line feed. Several control keys will 
also cause immediate system response. For example, CTRL-C is used to abort the execution of a running 
program. If the program is waiting for input, one CTRL-C will cause an immediate abort. J£ the program is 
not w aiting for input, it is necessary to type two CTRL-Cs to get the system's attention to abort a program. 

When a program requests terminal input, TSX-Plus puts the program in a suspended state until an activation 
character is typed. This state, in which a program is waiting for input but no activation character has been 
typed, is identified as the TI state by the SYSTAT command. When characters are typed at the terminal, 
TSX-Plus responds quickly and stores them in the terminal input buffer for that line, then returns to 
process other jobs which need its attention. Thus, the amount of time the CPU spends processing input 
characters is kept to a minimum, and the amount of CPU time used by a program in the TI state is also 
very ismall. Some programs request single characters with the .TTYIN request. Normally, these programs 
are treated by TSX-Plus in the same way as those requesting lines of input (e.g., .GTLIN requests). That 
is, the job is suspended, input characters are stored in the terminal input buffer, and characters are only 
passed to the program after an activation character is typed. K a program requests a character with a single 
.TTYIN, the user can type as many characters as the terminal input buffer will hold (allocated during system 
generation), but the program will remain suspended and no characters are passed to the program. Then, 
when an activation is typed, the program is restored to an active state, the first character in the input buffer 
is pasised to the program and processing continues. K the program requested no more characters, then on 
program exit the remainder of the input buffer, including the activation character, would be passed to the 
next program (usually the keyboard monitor) which would try to interpret them. This may result in an 
invalid command error message. 

15 
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3.1.2 Single character activation 

TSX-Plus gives the programmer a wide variety of ways to influence the normal input scheme outlined 
above. One of the most common methods is the use of single character activation. With this technique, all 
characters are regarded as activation characters. If a program requests a single character with a .TTYIN, 
then as soon as a character is typed and becomes available in the input buffer, it is passed to the program 
and the program resumes execution. 

The standard way to request single character activation under RT-11 is by setting bit 12 in the user's Job 
Status Word (JSW). Under TSX-Plus, this is not by itself sufficient to cause single character activation. 
The reason is that quite a few programs designed for a single user environment use thb method in a way 
that causes constant looping back and consequently burnt up a large amount of processor time. In a single 
user environment this is of minor importance since no other jobs are trying to use the processor at the same 
time. In a multi-user system, this is wasteful and should be avoided. Therefore, under TSX-Plus, setting 
bit 12 in the JSW b not by itself sufficient to initiate single character activation. It is necessary BOTH to 
set bit 12 and to issue a special command to TSX-Plus indicating that single character activation is actually 
desired. This may be done in any of the following ways: 

• Specify the /SINGLECHAR switch with the RUN or R command that starts the program. 

• Issue a SET TERMINAL SINGLE command. 

• Use the INSTALL command to install the program with the SINGLECHAR attribute (the description 
of the INSTALL command is in the TSX-Plue System Manager's Guide. 

• Use the "S" program controlled terminal option described in this chapter. 

Note that when a program is in single character activation mode, the system does not echo terminal input, 
it is the program's responsibility to do so. 

3.1.3 Non-blocking .TTINR 

The situation in which a program requests single characters but none are available in the input buffer also 
receives special treatment. The single character input request is eventually coded as EMT 340. The .TTYIN 
request repeats this request until a character is finally obtained, whereas the .TTINR request supposedly 
permits processing to continue if no character is available. In fact, the EMT 840 call will suspend the job 
until a character is available from the input buffer. This is referred to as stalling on a .TTYIN. The purpose 
is to avoid the unnecessary looping back to get a character. Under RT-11, if the programmer decides not 
to wait for a character to become available, but rather proceed with execution, it is only necessary to set 
bit 6 (100 octal) in the Job Status Word. Some programs abuse this technique and would waste the system 
resources in a time-sharing environment. TSX-Plus requires confirmation that the user is aware of the extra 
system load that could be caused by the constant looping back to check for a character. If you wish to have 
TSX-Plus return from the EMT S40 with the carry flag set if a character is not available, you must set bit 
6 in the Job Status Word and also do one of the following things: 

• Specify the /SINGLECHAR switch with the RUN or R command that starts the program. 

• Issue a SET TERMINAL NO WAIT command. 

• Use the INSTALL command to install the program with the NOWAIT attribute (the description of 
the INSTALL command is in the TSX-Plus System Manager's Guide. 

• Use the "U" program controlled terminal option described in this chapter. 
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3.1.4 Non-blocking .TTOUTR 

Normally when a program sends output to the terminal using a .WRITE, .PRINT, .TTYOUT, or .TTOUTR 
EMT, if the terminal output buffer is full, TSX-Plus suspends the program until space becomes available in 
the output buffer. K you wish to use the .TTOUTR EMT to send output to the terminal and have TSX-Plus 
return from the EMT with the carry flag set if the output buffer is full, you must do the following things: 

• Use the .TTOUTR EMT rather than .TTYOUT. 

• Set bit 6 in the Job Status Word. 

• The instruction following the .TTOUTR EMT must not be [BCS .-2j. 

• The program must be run with no-wait mode by performing one of the following actions: 

- Specify the /SINGLECHAR qualifier with the RUN or R command that starts the program. 

- Issue a SET TERMINAL NO WAIT command. 

- Use the INSTALL command to install the program with the NO WAIT attribute. 

- Use the "U" program controlled terminal option described in this chapter. 

TSX-Plus allows many other ways of modifying terminal input and output for special circumstances. These 
are provided to allow maximum versatility in the system while still maintaining the high efficiency needed 
in a multi-user environment. The programmer communicates the need for special terminal handling to the 
system through the use of special program controlled termmal optioria. These are described individually in 
the next section. 



3.2 Program controlled terminal options 

The following table lists the functions which may be used during program execution. 



Function Character 


Meaning 


A 


Set rubout filler character 


B 


Enable VT52 & VTIOO escape-letter activation 


C 


Disable VT52 & VTlOO escape-letter activation 


D 


Define new activation character 


E 


Turn on character echoing 


F 


Turn off character echoing 


H 


Disable subprocesses 


I 


Enable lower case input 


J 


Disable lower case input 


K 


Enable deferred character echo mode 


L 


Disable deferred character echo mode 


M 


Set transparency mode for output 


N 


Suspend command file input 


O 


Restart command file input 


P 


Reset activation character 


Q 


Set activation on field width 


R 


Turn on high-efficiency TTY mode 


s 


Turn on single-character activation mode 


T 


Turn off single-character activation mode 


U 


Enable no-wait TT input test 


V 


Set field width limit 


W 


Turn tape mode on 


X 


Turn tape mode off 


Y 


Disable echo of line-feed after carriage-return 


Z 


Enable echo of line-feed after carriage-return 
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These functions have a temporary effect and are automatically reset to their normal values when a program 
exits to the keyboard monitor. They are not reset if the program chains to another program until control is 
finally returned to the monitor. Some terminal options (notably high-efficiency and single-character modes) 
are incompatible with, and override, some other terminal options. 

TSX-Plus provides two methods for a running program to dynamically alter some of the parameter settings 
relating to the user's timesharing line. The preferred method of selecting these functions is to use the TSX- 
Plus EMT for that purpose. Thb is readily available from MACRO programs and an appropriate MACRO 
subroutine should be linked into jobs written in other languages. The form of the EMT to select program 
controlled terminal options is: 



ENT 



375 



with RO pointing to the following argument block: 

.BYTE 0.152 

.WORD function- code 

.WORD argument -value 

where function- code is the character from the table above which selects the terminal option, and argument- 
value may be a third value used only with some of the functions. An advantage of the EMT method 
of selecting program controlled terminal options is that they may be used even when the terminal is in 
high-efficiency mode. 

Example 



.TITLE ENTNTH 

.ENABL LC 
Draonitrat* TSX--Plai program controlled tvralnal optioni uiing 
th« ENT aothod. 

.MCALL .GVAL.. PUNT.. EXIT,. TTYIN 

.OLOBL PITDBC 
Dotoralno uid ditplaj earront Itad-ln char 
Default ■ 36, but don't count on It 



:DttorBlno eurrtnt Itadin character 

:SaTe it 

; "Current lead-in la" 

;KetrieTe lead-in char value 

:Diepla7 it 



STAIT: .GTAL iAiEA,i-4. 

NOV 10,11 

.PlIKT iLBADIS 

NOV 11,10 

CALL PITDEC 

.PUNT tLEADNB 
; Set rnbout filler character 

NOV iSETlUB,10 

ENT 376 
Now deaonetrate the current 
; Back space ii the default, which we changed to underline 



{Point to ENT arg block to 
:Set rubont filler character 
rubout filler character 



It: 



21: 

AREA: 
SETIUB : 



TRYIT: 



LEA0I8 
LEADNB 
THANIS 
BUFFER 
BUFEND 



.PUNT 

NOV 

.TTYIN 

CNPB 

BEQ 

CNP 

BLO 

.PUNT 

.EXIT 

.BLXW 

.BYTE 

.WOID 

.WOID 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCIZ 

.ASCIZ 

.BLIB 

.END 



#T1YIT 
fBOFFEl.ll 

10. #12 

2t 

ll.iBUFEND 

11 

iTHANKS 



; "Enter aoBo and delete thea" 

;Point to input buffer 

:Get next char into input buffer 

:End of input (Cl/LF palr)T 

:Yea. teralnate input 

{Buffer oTorflowT 

;Get Bore if not 



10 {General ENT arg block 

0,162 {ENT arg block to 

'A {Set rubout filler character 

'_ {to underline 

/Enter eoHO charactera at the proapt and then / 

/eraae thea with/<16><12>/DELETE or CTIL-U./ 

/ The7 should be replaced with underlinea./<16><12>/«/<200> 

/Ve don't care that the current lead-in char ia /<200> 

/./ 

<16><12>/ST0P — Thank you./ 

81. 

STAIT 
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When it is not practical to incorporate the EMT method of selecting program controlled terminal options 
into a program, an alternate method using a Uad-in character may be used. This is conveniently done by 
sending a sequence of characters to the terminal using the normal terminal output operations of the lan- 
guage. Examples are the FORTRAN TYPE, COBOL-Plus DISPLAY, BASIC PRINT, and Pascal WRITE 
statements. Program controlled terminal options are selected by having the running program send the 
lead-in character immediately followed by the function character and, for some functions, a third character 
defining the argument value for the function. TSX-Plus intercepts the lead-in character and the one or two 
foUovang characters and sets the appropriate terminal option. It does not pass these intercepted characters 
through to the terminal. The default value for the lead-in character is the ASCII GS character (octal value 
S5; decimal value 29). However, the lead-in character may be redefined during system generation when the 
value conflicts with other uses of the system. For example, some graphics terminals use the GS character 
as either a command or parameter value. The lead-in character function may be disabled during program 
execution with the M and R functions described below. Programmers should not rely on the default value 
of the lead-in character, but may obtain the current value of the lead-in character from the .GVAL request 
with an offset of -4. 

Note that when in high-efficiency mode (set with either the RUN/HIGH switch or the "R** program controlled 
terminal option) output character checking is disabled and the lead-in character method of selecting program 
controlled terminal options is disabled; in this case, the lead-in character, function-code character, and 
argument value character are passed through to the terminal. When in high-efficiency mode, the EMT 
method of selecting program controlled terminal options is still functional. See Chapter 4 for information 
on turning high-efficiency terminal mode off by means of an EMT. 

Example 

PEOGRAN LEADIN 
C 

C Deiionitratt TSX — Plus progrui controlled tormlnal optloni aslng 
C th» "Icftd-ln" characttr Bothod. 
C 

BYTE LEADIN (2) 

INTEGE& I LEAD 

EQUIVALENCE (ILEAD, LEADIN (1)) 
C Dolbtrmln* uid display currant laad-ln char 
C Default > 29, but don't count on It 

ILEAD - ISPT(-4) I. GVAL with offaat - -4. 

TYPE 820,LBADIN(1) IDlaplay tho currant laad-in char Talua 
C Sat rubout flllar character 

TYPE 800,LEADIN(1),'A','_' 
C Now daaonatrato the currant rubout filler character 
C Back apace la the default, which we changed to underline 

TYPE 810 lAak for aomethlng to be eraaed 

ACCEPT 830 I Walt for Input before exiting 

STOP 'Thank you. ' 
800 FORMAT (1H+,A1,$) 

810 FORMAT (IHO, 'Enter aoae charactert at the prompt and then '. 
1 'erase thea with'/' DELETE or CTU-U.'. 
i ' They should be replaced with underlines.'/' «'.$) 
820 FORNATC The current ralue of the lead-in character Is '.IS,'.') 
830 FORMAT (40H ) 

END 

The following paragraphs explain the uses of each of the program controlled terminal option function-codes. 
Any of these options may be selected by either the EMT method or by the lead-in character method. 

3.2.1 "A" function — Set rubout filler character 

When a scope type terminal is being used, the normal response of TSX-Plus to a DELETE character is to 
echo backspace space backspace which replaces the last character typed with a space. TSX-Plus responds to 
a CTRL-U character in a similar fashion, echoing a series of backspaces and spaces. Some programs that 
dispLaiy forms use underscores or periods to indicate the fields where the user may enter values. In this case it 
is desirable for TSX-Plus to echo backspace character backspace for DELETE and CTRL-U where character 
may be period or underscore as used in the form. The character to use as a rubout filler is specified by the 
argument-value with the EMT method or by the third character with the lead-in character method. 



20 CHAPTER 3. PROGRAM CONTROLLED TERMINAL OPTIONS 

3.2.2 "B" & "C functions — Set VT52, VTIOO and VT200 escape-letter ac- 
tivation 

VT52, VTlOO and VT200 terminals are equipped with a set of special function keys marked with arrows 
and other symbols. When pressed, they transmit two or three character escape sequences. The "B" function 
tells TSX-Plus to consider these as activation sequences. The escape character and the letter are not echoed 
to the terminal, but are passed to the user program. The "C function dbables this processing and causes 
escape to be treated as a normal character (initial setting). 

3.2.3 "D" function — Define new activation character 

Under normal circumstances TSX-Plus only schedules a job for execution and passes it a line of input when 
an activation character such as carriage return b received. The "D" function provides the user with the 
ability to define a set of activation characters in addition to carriage return. 

The new activation character is specified by the argument-value with the EMT method or by the third 
character with the lead-in character method. The maximum number of activation characters that a program 
may define b specified when the TSX-Plus system b generated. 

Using thb technique, any character may be defined as an activation character, including such characters as 
letters, DELETE, CTRL-U, and CTRL-C. When a user-defined activation character b received, it b not 
echoed but b placed in the user's input buffer which b then passed to the running program. 

By specifying CTRL-C as an activation character, a program may lock itself to a terminal in such a fashion 
that the user may not break out of the program in an uncontrolled manner. 

K carriage return b specified as a user activation character, neither it nor a following line feed will be echoed 
to the terminal. TSX-Plus will also not add a line feed to the input passed to the program. 

3.2.4 "E** and "F" functions — Control character echoing 

The "E" and "F" functions are used to turn on and off character echoing. The "E" function turns it on, and 
the "F" function turns it off. An example of a possible use b to turn off echoing while a password b being 
entered. 

3.2.5 "H" function — Disable subprocess use 

The "H" function disables the subprocess window facility for the time-sharing line. 

3.2.6 **P and "J" functions — Control lower case input 

The "I" function allows lower case characters to be passed to the running program. The **J** function causes 
TSX-Plus to translate lower case letters to upper case letters. The SET TT [NO]LC keyboard command 
also performs these functions. 

3.2.7 "K" and "L" functions — Control character echoing 

The "K" function causes TSX-Plus to enter deferred character echo mode. The "L" function causes TSX- 
Plus to enter immediate character echo mode. Any characters in the input buffer which have not been 
echoed when the "L" function b selected will be immediately echoed. See the description of the SET TT 
[NOJDEFER command for an explanation of deferred echo mode. 
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3.2.8 ^'M" function — Set transparency mode of output 

If transparency mode is set, TSX-Plus will pass each transmitted chtiracter through to the program without 
performing any special checking or processing. Transparency mode allows the user's program to send any 
character to the terminal. Note that once transparency mode is set on, TSX-Plus will no longer recognize 
the lead-in character (octal 85, which means a program control function follows). The only way to turn off 
transparency mode is to exit to KMON. 

3.2.9 **N'' and "O" Functions — Control command file input 

When a command file is being used to run programs (see the TSX-Plua U»er'» Reference Manual), input 
which would normally come from the user's terminal is instead drawn from the command file. Occasionally, 
it is desirable to allow a program running from a command file to accept input from the user's terminal 
rather than the command file. The "N" function suspends input from the command file so that subsequent 
input operations will be diverted to the terminal. The "O" function redirects input to the command file. 
These functions are ignored by TSX-Plus if the program is not being run from a command file. 

3.2.10 **?" function — Reset activation character 

The "P" function performs the complement operation to the "D" function. The "P" function is used to 
remove an activation character that was previously defined by the "D" function. The character to be 
removed from the activation character list is specified by the argument-value with the EMT method or by 
the thiird character with the lead-in character method. 

Only activation characters that were previously defined by the "D" function may be removed by the "P" 
function. 

3.2.11 "Q" function — Set activation on field width 

The "Q" function allows the user to define the width of an input field so that activation will occur if the user 
types in as many characters as the field width, even if no activation character is entered. The field width 
is specified by the ASCII code value of the argument-value with the EMT method or of the third character 
with the lead-in character method. If an activation character is entered before the field is filled, the program 
will be activated as usual. Each time activation occurs the field width is reset and must be set again for the 
next field by reissuing the "Q" function. For example, the following sequence of characters could be sent to 
TSX-Plus to establish a field width of 4S characters: '*</cod-»n>Q+''. Note that the character "+" has the 
ASCII code of 053 (octal) which is 4S decimal. 

3.2.12 •'R" function — Turn on high-efficiency terminal mode 

The "R" function causes TSX-Plus to place the line in high efficiency terminal mode. The effect is to 
disable most of the character testing overhead that is done by TSX-Plus as characters are transmitted 
and received by the line. Before entering high-efficiency mode the program must declare a user-defined 
activation character that will signal the end of an input record. Once a program has entered high-efficiency 
mode, characters sent to the terminal are processed with minimum system overhead. For example, tab 
characters are not expanded to spaces. Also, TSX-Plus does not check to see if the character being sent 
is the TSX-Plus terminal control leadin character. This means that the lead-in character method may not 
be used to control terminal options until the program exits or the EMT to turn off high efficiency mode 
is used (see Chapter 4). Characters received from the terminal are passed to the program with minimum 
procesising: they are not echoed; and control characters such as DELETE, CTRL-U, CTRL-C, CTRL-W 
and carriage-return are all treated as ordinary characters and passed directly to the program. High-efficiency 
mode terminal I/O is designed to facilitate machine-to-machine communication; it is also useful for dealing 
with buffered terminals that transmit a page of information at a time. 
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3.2.13 "S" function — Turn on single-character activation mode 

The "S" function causes TSX-Plus to allow a program to do single-character activation by setting bit 12 in 
the Job Status Word. Normally TSX-Plus stores characters received from the terminal and only activates 
the program and passes the characters to it when an activation character, such as carriage-return, is received. 
It does this even if bit 12 is set in the Job Status Word, which under RT-11 causes the program to be passed 
characters one-by-one as they are received from the terminal. The •'S" function can be used to cause TSX- 
Plus to honor bit 12 in the Job Status Word. If JSW bit 12 is set and the program is in single-character 
activation mode, TSX-Plus passes characters one-by-one to the program as they are received and does not 
echo the characters to the terminal. The /SINGLECHAR switch for the R[UNl command and the SET TT 
SINGLE command can also be used to cause TSX-Plus to honor JSW bit 12. Since the high-efficiency mode 
implies certain terminal characteristics (such as buffered input and no echo), it is not possible to override 
these inherent modes by using other function codes. 

3.2.14 *'T'' function — Turn off single-character activation mode 

The "T" function is the complement of the "S" function. It turns oif single-character activation mode. 

3.2.15 ^'U" function — Enable non-wait TT I/O testing 

The "U" function causes TSX-Plus to allow a program to do a .TTINR EMT that will return with the carry 
bit set if no terminal input is pending or a .TTOUTR EMT that will return with the carry bit set if the 
terminal output buffer is full. Normally TSX-Plus suspends the execution of a program if it attempts to 
obtain a terminal character by doing a .TTINR EMT and no input characters are available. Or if it does a 
.TTYOUT or .TTOUTR EMT and there is no free space in the terminal output buffer. It does this even 
if bit 6 of the Job Status Word is set, which under RT-11 would enable non-blocking .TTINRs. This is 
done to prevent programs from burning up CPU time by constantly looping back to see if terminal input is 
available. The "U" function causes TSX-Plus to honor bit 6 in the Job Status Word and allows a program 
to do a .TTINR to check for pending TT input or a .TTOUTR EMT to check for space in the output buffer 
without blocking if none is available. The SET TT NO WAIT command and the /SINGLECHAR switch for 
the R{UN] command also perform this function. Because the single character terminal option determines 
several terminal operating modes (such as no echo and transparent input), it is incompatible with other 
terminal functions which would conflict with the implied single-character operation. See the description of 
special terminal mode in the RT-11 Programmer '» Reference Manual. 

3.2.16 **V» function — Set field width limit 

The "V function is used to set a limit on the number of characters that c«ui be entered in the next terminal 
input field. Once the "V function is used to set a field limit, if the user types in more characters to the 
field than the specified limit, the excess characters are discarded and the bell is rung rather than echoing the 
characters. An activation character still must be entered to complete the input. The field width is specified 
by the ASCII code value of the argument-value with the EMT method or of the third character with the 
lead-in character method. The field size limit b automatically reset after each field is accepted and must be 
re-specified for each field to which a limit is to be applied. Note the difference between the "Q" and "V" 
functions. The "Q" function sets a field size which causes automatic activation when the field is filled; the 
"V" function sets a field size which causes characters to be discarded if they exceed the field size. Note that 
any field width limit is ignored for command file input. 

3.2.17 ''W'* and "X" functions — Control tape mode 

The "W" function turns on tape mode and the "X" function turns it off. Turning on tape mode causes the 
system to ignore line-feed characters received from the terminal or external device. The SET TT [NO|TAPE 
keyboard command may also be used to control tape mode. 
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3.2.18 "Y" and "Z" functions — Control line-feed echo 

The "Y" function is used to disable the echoing of a line-feed character when a carriage-return is received. 
Normally, when TSX-Plus receives a carriage-return character, it echoes carriage-return and line-feed char- 
acters to the terminal and passes carriage-return and line-feed characters to the program. The "Y" function 
alters this behavior so that it only echoes carriage-return but still passes both carriage-return and line-feed 
to the program. This function can be used to advantage with programs that do cursor positioning and which 
do not want line-feed echoed because it might cause the screen display to scroll up a line. The "Z" function 
restores the line- feed echoing to its normal mode. 
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Chapter 4 



TSX-Plus EMTs 



TSX-Plu8 provides several system service calls (EMTs) in addition to those compatible with RT-11. In 
order to take advantage of the special features of TSX-Plus, programs written to run under both TSX-Plus 
and RT-11 should check to see if they are under TSX-Plus. This chapter describes the preferred method of 
checking and goes on to describe several of the special EMTs provided by TSX-Plus. EMTs which relate 
specifically to features described elsewhere in this manual are included in the appropriate chapters. 



4.1 Obtaining TSX-Plus system values (.GVAL) 

The .GVAL EMT that is normally used to obtain RT-11 system values can also be used to obtain TSX-Plus 
system values. Although a simulated RMON is normally mapped into each job so that it may directly access 
fixed offsets into RMON, the .GVAL function is the preferred method for obtaining system values. Under 
TSX-Plus, the simulated RMON need not be mapped into a job's virtual address space (see Chapter 2). 
The .GVAL EMT will still function correctly even if RMON is not mapped into the job. In addition to the 
positive offset values which are documented for use with RT-11, the following negative oflFset values may be 
used to obtain TSX-Plus system values: 



Offset 



-2. 

-4. 

-6. 

-8. 
-10. 
-12. 
-14. 
-16. 
-18. 
-20. 
-22. 
-24. 

-26. 
-28. 
-30. 

-32. 
-34. 



Value 



Job number 

Lead-in character used for terminal control options 
1 if job has SYSPRV privilege; if job does not have SYSPRV 
1 if PAR 7 mapped to I/O page; otherwise 
Project number job is logged on under 
Programmer number job is logged on under 
TSX-Plus incremental license number 
Current job priority 
Maximum allowed job priority 
Number of blocks per job in SY:TSXUCL.TSX 

Job number of primary process (0 if primary process, always for detached jobs) 
Name of system device (RAD50) (device on which RT-11 was booted when TSX- 
Plus was started; may not correspond to current SY assignment) 
Maximum fixed-low-priority value 
Minimum fixed-high-priority value 

Job number of parent process (0 if primary process, same as offset -22. if subpro- 
cess) 

System version number — Decimal value times 100. 

Relative subprocess number (O if primary process or detached job) 
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As with the standard .GVAL function, the system values are returned in RO. 



Example 





.TITLE 


TSGVAL 






.EN&BL 


LC 




;DeBonstratt ns 


aga of .GVAL with 


both poiitlTa (ET-11) 


: and negatlra 


(TSX-Plus) offaets 






.NCALL 


.GVAL,. PlINT,. EXIT 




.GLOBL 


PETDEC ; 


Subroutlno to print a vord in declBal 




.GLOBL 


PETIBO : 


Subroutlna to print a EADBO word 


SYSGEM 


« S72 




ENON offaot to aytgan optlona word 


SIA&T: 


.OVAL 


iA&EA,fSYSGEN ; 


Exaalno ayttaa optloni word 




TST 


10 


Sta If wa ara runninf TSX-Plui 




BPL 


91 


Exit if not 




.PUNT 


fLICENS 


•*Liconia « li" 




.GVAL 


tA&EA,t-14. 


Obtain lait 4 digits of llcanaa i 




CALL 


PETDEC 


And display It 




•PlINT 


iSYSTEN 


"Startad fro«" 




.GVAL 


iAEEA,f-24. 


Got ayitoB darica 




CALL 


PETIBO 


;And display It 




.PtINT 


iJOBNDN 


:"Job # is" 




.GVAL 


iAEEA.i-2 


;Gat TSX-Plus Job nuabar 




CALL 


PETDEC 


:Displa7 tha Job nuabor 




.GVAL 


•AEEA,«-a2. 


;Saa if this is tha priaary Una 




TSI 


EO 


;0 if primary 




BEQ 


91 


:Dona if so 




.PlIHT 


iVIET 


;Elsa say sabprocass 


91: 


.EXIT 






AIEA: 


.BLIV 


2 


;2 word EMT arg araa 




.NLIST 


BEX 




LICENS : 


.ASCII 


/TSX-Pluf lleani 


I nuBber /<200> 


SYSTEM: 


.ASCII 


<16><12>/TSX-Plui 


1 startad from /<200> 


JOBNUN 


.ASCII 


/:/<lB><12>/TSX-I 


>1U8 Una nuBbar /<200> 


VIIT: 


.ASCII 


/ (Thla !■ a aub 


proeass)/<200> 




.END 


8TAET 





4.2 Determining number of free blocks in spool file 

The following EMT will return in RO the number of free blocks in the spool file. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 0.107 



Example 



.TITLE 8PLFEE 

.ENABL LC 
;DaBonatrata ENT to dataralna nuabar of fraa apool blocks 

.NCALL .PEINT,.EXIT 

.GLOBL PETDEC 

STAET: .PEINT *NUNFEE 

MOV fSPLFEE.EO 

ENT 376 



CALL PETDEC 

.PEINT fBLOKS 

.EXIT 

.NLIST BEX 

SPLFEE: .BYTE 0,107 

NTTHFEE: .ASCII /Tha spool flla haa /<200> 

BLOXS: .ASCIZ / fraa blocks./ 

.EVEN 

.END STAET 



;Prafaca ntubar massaga 

:Polnt to ENT arg block to 

:DatarHlna ntmbar of fraa spool blocks 

:NuBbor is raturnad in EO 

;DlBplay tha nuabar 

;End of aassaga 



:ENT arg to gat i fraa apool blocks 



4,3. DETERMINING IF A JOB IS RUNNING UNDER TSX-PLUS 
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4.3 Determining if a job is running under TSX-Plus 

In cooperation with Digital Equipment Corporation, a bit has been allocated in the RT-11 sysgen options 
word at fixed offset 372 into the RMON. The high order bit (bit 15; mask 100000) of this word will be set (l) 
if the current monitor is TSX-Plus version 5.0 or later. This bit will be clear if the monitor is any version 
of RT-11. Testing this bit is the preferred method of determining if a job is running under TSX-Plus. 
However, if a program is expected to also be used under older versions of TSX-Plus, then an alternative 
method is necessary. For older versions of TSX-Plus, first issue the .SERR request to trap invalid EMT 
requests and then issue the TSX-Plus EMT to determine the time-sharing line number. If the job is running 
under RT-11, this EMT will be invalid and the carry bit (indicating an error) will be set on return. If the 
job is running under TSX-Plus, then the EMT will return without error and the line number will be in RO. 

Exannple 



.TITLE TSXENV 

.ENABL LC 
DcBonitrat* prtferrtd M«thod of det«rHlnlng whathvr Job It 
rannlng tindor TSX-Plut or lT-11 

.NCALL .PRINT,. EXIT.. SE&i,.H£U 



JSV - 44 

INON - 54 

SYSGEN - S72 

STAIT: .FEINT «UNDEi 

; Thill !■ tho prefarrod method, 

; TSX-PluB Torsion 6.0 

NOV INON, 11 

TST SYSGEN (Rl) 

BPL RTll 
Thill it tht old Bothod, but will work correctly with 
all Toriioni of TSX-Plui 



;Job Status Word address 

;Pointer to base of RNON 

; Index into RNON for sjsgen features 

; "Running under" 

but will not work prior to 

iPoint to base of RNON 

;See if running under TSX-Plus 
;Branch if running under RT-11 



RTll; 



TSXLN:: 

UNDER:: 
TSXPLS : 
NOTPLS : 



.SERR 

NOV 

ENT 

BCS 

.PRINT 

.EXIT 

.KERR 

.PRINT 

.EXIT 

.BYTE 

.NLIST 

.ASCII 

.ASCIZ 

.ASCIZ 

.END 



»TSXLN,RO 
S76 
RTll 
iTSXPLS 



«NOTPLS 



;Trap Inralid ENT error 
;Polnt to ENT arg block to 
;Deteralne TSX-Plus line number 
;Branch if running under RT-li 
: "TSX-Plus" 

;Reset SERR trap 
;"RT-11" 



0,110 

BEX 

/Nonitor is /<200> 

/TSX-Plus./ 

/RT-11./ 

START 



;ENT arg block to get line number 



4.4 Determining the TSX-Plus line number 

The following EMT will return in RO the number of the line to which the job is attached. Physical lines are 
numbered consecutively starting at 1 in the same order as specified when TSX-Plus is generated. Detached 
job lines occur next and subprocesses are numbered last. 

The form of the EMT is: 



EMT 375 

with RO pointing to the following argument area: 
.BYTE 0,110 
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Example 



.TITLE LNTT 

.BNiBL LC 
What TSX lln* number !■ thlt ttrmlnal attachtd toT 
Ind what type tarmlnal doii TSX-Plui think It liT 
.PilNT, .EXIT. .TTYOUT, .SERE. .HKU 



STAIT: 



.NCALL 
.6L0BL 

.SEU 

NOV 

ENT 

BC8 

MOV 

.KEIl 

.PlINT 

NOV 

CALL 

.PIIHT 

NOV 

ENT 



P&TDEC 



fTSXLN.lO 
S7B 

NOTTSX 
10, LINE 

iLINNSG 

LINE.EO 

PITDEC 

«T&NNSG 

#TTTPE,10 

376 



NOTTSX 

LINE: 
TEUI: 
TSXLN: 
TTYPB: 



TYPE 



LINNSG 

TENNSG 

TSXEU 

UNI: 

VTfi2: 

VTIOO 

HAZEL 

ADN3A 

LA36: 

LAi20: 

DIABLO 

qUNE: 

VT200: 



fTSXEEI 




0,110 
0,157 



ASL 10 
.PUNT TYPE (10) 
.EXIT 
.PUNT 
.EXIT 
.WOID 
.VOID 
.BYTE 
.BYTE 
Tabl* of polnttri to 
.EVEN 
.WOID 
.WOIF 
.NLIST 
.ASCII 
.ASCII 
.ASCIZ 
.A8CIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.EVEN 
.END 8TA1T 



;Subroutlnt to print a word in dtclmal 

:Ar« vt under TSX-PlneT 

;Stop orror aborta 

;Stt up ENT raqutat to 

;G«t TEX-Plus lint nuabar 

:If orror, not under TSX-Plue 

;8aTe it 

;Enablo error aborte 

iDlaplay lino nnaber aeaaago 

;lecall line number 

; Display line number 

;Diipla7 term type meaaage 

;Set up ENT requeet to 

;Got terminal type from TSX-Plua 

;leturni into 10 

:ConTert to word oflaet 

;Print type from index Into table 

:A11 done 

;Say ve are not under TSX-Plna 



; Storage for TSX line number 
;Storage for TSX term type code 
;TSX line number ENT parameter a 
;TSX term type ENT parameters 
TSX term type names 



UNI. VTE3, VTIOO , HAZEL ,ADN3A ,LA3e ,LA120 

DIABLO, qUNE,VT200 

BEX 

/TSX-Plus line number: /<200> 

<16><12>/Terainal type: /<200> 

/TLNTT-F-Not running under TSX-Plus/ 

/Unknown/ 

/VTB2/ 

/VTIOO/ 

/Hazeltine/ 

/ADN3A/ 

/LA3e/ 

/LA120/ 

/Diablo/ 

/Qume/ 

/VT200/ 



; Diablo and Qume are equiTalent 
; Diablo and Qume are equiTalent 



4.5 Determining subprocess job number 

The following EMT may be used to determine the line number on which subprocesses axe executing. This 
b useful in conjunction with the EMT to initiate a subprocess. 

The form of the EMT used to determine a subprocess job number is: 



EMT 37B 

with RO pointing to an argument block of the following form: 



4.6. SET/RESET ODT ACTIVATION MODE 
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.BYTE l.liO 

.WORD relative-subprocesB-number 

The relative subprocess number is in the range 1 - MAXSEC, and is the same as the number used when 
switching to a subprocess from the keyboard with the <"W><n> sequence. In absence of an error, this EMT 
returns in RO the line number on which the subprocess is running. This EMT can return the following error 
codes: 



4.6 Set/Reset ODT activation mode 



The following EMT can be used to set TSX-Plua to activate on characters that are appropriate to ODT. 
In this mode TSX-Plus considers all characters to be activation characters except digits, ",", "$", and ";". 
The form of the EMT is: 



EMT 



375 



with RO pointing to the following argument area: 

.BYTE code. Ill 
where code=l to turn on ODT activation mode, and code=0 to reset to normal mode. 
Example 



;DMonii 
STAKT 

II: 



21: 



SETLIN: 



TITLE ACTODT 
ENABL LC 
trat* ENT which lets ODT 
NCALL .PUNT.. EXIT 

♦ODTTYP 

f ACTODT. 10 

S7E 

6ETLIN 

BUFFEE.i'q 

It 

«&EGTYP 

ACTODT 

f ACTODT. iO 

37B 

CETLIN 

BUFFEK.i'Q 

2$ 



ACTODT: 
TTIBLI: 



ODTTYP: 
lEGTTP: 
P&ONPT : 

BUFFEl: 



.PEIKT 

NOV 

ENT 

CALL 

CHPB 

BNB 

.PlINT 

CL&B 

NOV 

ENT 

CALL 

CNPB 

BNE 

.EXIT 

.PRINT 

NOV 

ENT 

CLEB 
.PEINT 

EETDEN 

.BYTE 

.BYTE 

.WOEO 

.WOED 

.NLIST 

.A8CIZ 

.ASCIZ 

.ASCII 

.EVEN 

.BLEB 

.BYTE 

.END 



iPEONPT 
#TTIBLI,EO 
S75 

BUFFER (EO) 
iBUFFEE 



actlTatlon aodt 

;Sa7 va arc antarlng ODT actlratlon mode 

:Polnt to ENT arg block to 

:Set ODT actlratlon aoda 

;Gat aoB* taralnal Input 

;Back to rtgular BodsT 

;No, got Bort llnaa 

iSay vo aro going back to rogular actlratlon 

:Naka arg block Into lESET Bodt roquoat 

;Polnt to ENT arg block to 

;Eeaot ODT activation Bodo 

;Gat Bora Input 

;Want to quit? 

:No. rapaat 

;Eaqueit aoBO Input 
:Polnt to ENT arg block to 
:Accapt a block of eharactera 
;Nak« Input atrlng ASCIZ 
;And acho aaaa atrlng back 



:ENT arg block to 8ET/EESET ODT act'n Boda 
;ENT arg block to got block Input froB tant 
:Polntar to Input buffar 
;NuBbar of Input chart raquaatad 



1,111 

0,116 

BUFFEE 

79. 

BEX 

/Starting ODT actlratlon Boda./ 

/Eaatorlng ragular actlratlon Boda./ 

/T/<200> 



79. 



START 



; TTIBLI Input buffar 

;CLEB could go hora on full buffar 
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4.7 Sending a block of characters to the terminal 

The following EMT can be used to efficiently send a block of characters to the terminal. The form of the 
EMT is: 

EHT 37B 

with RO pointing to the following argument block: 

.BYTE 0.114 
.WORD buffer 
.WORD count 

where buffer is the address of the buffer containing the characters to be sent and count is a count of the 
number of characters to be sent. This EMT is much more efficient to use than a series of .TTYOUT EMTs — 
it has the same efficiency as a .PRINT EMT but it uses a count of the number of characters to send rather 
than having the character string in ASCIZ form. 



Example 

.TITLE 

.BNABL 

;DeBonatration 

'.characters to 

.NCALL 



ST AIT : 



TTOBLK: 



BUFFEl: 



BUFEND: 



NOV 

ENT 

.EXIT 

.BYTE 

.VOID 

.VO&D 

.NLIST 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.ASCII 

.END 



TTOBLI 

LC 

of tha aat of tha TSX-Plai ENT to aand a block of 
tha taralnal. 

.EXIT 

«TTOBLI,10 ;Polnt to ENT arg block to 

S76 ;Sand a block of chart to tha tarBlnal 

0,114 ;ENT arg block to aand a block of chara 

BUFFEl ;Polntar to charactar baffar 

<BUFEMD-BnFFBR> ; Count of charactart to ba output 

BEX 

/This ENT la uaad to aand a block of eharactora / 

/to tha tarKinal./<16><12> 

/It la almllar to .PRINT, axcapt that it naea / 

/a count of charactarB/<lE><12> 

/rathar than a apaclal taralnatlng charactar / 

/(<0> or <200>)./<lB><12> 

STAIT 



4.8 Accepting a block of characters from the terminal 

The following EMT can be used to accept all characters from the terminal input buffer up to and including 
the last activation character entered. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 



.BYTE 
.WORD 
.WORD 



0.115 

buffer 

•iz« 



where buffer is the address of the buffer where the characters are to be stored and size is the size of the 
buffer (number of bytes). This EMT causes a program to wait until an activation character is entered and 
then returns all characters received up to and including the last activation character. On return RO contains 
a count of the number of characters received. If the specified buffer overflows, the carry flag is set on return. 
This EMT is substantially more efficient than doing a series of .TTYIN EMTs; it is particularly well suited 
for accepting input from page buffered terminals. 



Example 



4.9. CHECKING FOR TERMINAL INPUT ERRORS 
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.TITLE TTIBLI 
.KNABL LC 
;D«Boniitrat«i th« us* of 

;tTom 



TSX-Plus ENT to acctpt a block of eh&racton 



ttrHlnal. 

.NCALL .EXIT,.PEINT 
STAKT: .PlINT fP&OMPT 

NOV *TTIBLI,&0 

ENT 375 

NOV 10, El 
;Char count Ineludet aetiTation 

BCC 1$ 

.PRINT #OVFLO¥ 
it: ADD «BUFFEIL,E1 
(El) 
iBUFFEE 



TTIBLI : 



PEONPT 
OVFLOW 
BUFFEE 

BUFEND: 



ADD 

CLEB 

.PEINT 

.EXIT 

.BYTE 

.WOED 

.WOED 

.NLIST 
.ASCIZ 
.ASCIZ 
.ASCII 
.ASCII 
.ASCII 
.END 



TTYIN 

;Eequott Input 

;Polnt to ENT arg block to 

;Accopt a block of ehara from tho 

;SaT« input eharactar count 

char (and LF after CE) 

; Buff or ororflov on Input? 

;Yei, warn utar 

;Polnt paat last char In buffer 

;Nake the Input ASCIZ 

;Eeproduco the Input 



teralnal 



0,116 ;EMT arg block to accept block froB terminal 

BUFFEE ; Start of input buffer 

<BUFEND-BUFFEE> ; Length of buffer in chart (Na^ not exceed 

: input buffer alio declared in TSGEN.) 
BEX 

/70 character input buffer ready./ 
/TTTIBLI-F-Buffer OTerflo*/ 

/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ :S6 chara 
/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ :36 chare 



/TT/ 
STAET 



; TTIBLI will nerer write over theae 



4.9 Checking for terminal input errors 

The following EMT can be used to determine if any terminal input errors have occurred. The form of the 
EMT is: 



EMT 



375 



with RO pointing to the following argument block: 
.BYTE 0.116 

On return from the EMT, the carry flag is set if an input error has occurred since the line logged on or since 
the last time a check was made for input errors. The two types of errors that are monitored by this EMT 
are hairdware reported errors (parity, silo overflow, etc.) and characters lost due to TSX-Plus input buff'er 
overflow. 

Example 



.TITLE CITTIE 
.ENABL LC 
: Check for teralnal input errori 

.NCALL .PEINT.. TTYIN.. EXIT 
STAET: .PEINT #PEONPT ;Aak to OTerflow buffer 

NOV *100.,E1 :Set up counter for Input loop 
NOV fSETTTO.EO jPoint to ENT arg block to 
ENT 376 ;Set terminal time out for 0.6 aece 

;Note ithat thia ia reset after OTery activation charaeterlil 
•.Start requeeting characters. Input characters are stacked in the user 
;lnput buffer until an actiTation character la seen (\eg carriage return) 
;8o, all ve have to do to oTorflov is enter more than the input buffer 
isise (defined in TSGEN either by DINSPC or with the BOFSIZ macro) 
;and t]rp« in too many before activating. 
:Use a time out so we do not have to hit return. 
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1$: .TTYIH ;Gtt a charftctcr from th« ttraln&l 

CNPB lO.iSr ;¥&■ it tlB«-eut actlT«tlon charT 
BBQ TINODT ;T«i, exit loop 
SOB 11,1$ -.lopaat for 100. eharactors 

;For a iTitM with Input bulfar ilit-lOO. In TSGEN, vo ahould bt 
;abl« to oTarflov th« buffar balora «t ••• an actlTatlon char 



TINOITT: NOV 
ENT 



HADEU: 



BC8 

.PUNT 

.EXIT 

.PUNT 

CMP 



ffCETTIE.iO -.Point to ENT arg block to 

375 : Chock for tondnal Input arrori 

HADERl ;8ay wo had orrora 

ffNOEBl ;Sa7 wo had no orrora 

«TESE&B. ;Error mosoago 

11, «S :Dld wo fill tho bufforT 



;Noto that laat two chart of input buffer ara rostrrod 
;for actiration chari . Any «xcaai input io diacardod. 



TOONNT: 



SETTTO : 



CITTIE: 

TESEUl 

OVFBU 
HDVEU 
NOEU: 
PIONPT 



BLE 

.PEINT 

.EXIT 

.PEINT 

.EXIT 

.BTTE 

.WOID 

.WOID 

.BTTE 

.NLIST 

.ASCIZ 

.iSCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



TOONNT 
iHDVEU 



fOVFEll 



;Toe, buffar oTorflow 

:No, hardware orror Boaaago 

;Buffor owarflow aaiaaga 



:ENT arg block to aat taralnal tlM* out 
;to 10 aoconda (20 half aac unlta) 
;PatBod ae actiwation char on tiao-out 
;ENT arg block to chock for input orrora 



o.iir 

20. 

37 

0.116 

BEX 

<lE><12>/Thoro woro orrori during teralnal input. /<7> 

/(Probably input buffar ororflow.)/ 

/(Probably hardware arror ... parity, atop blta. data biti)/ 

<16><12>/Thoro wera no terBlnal input arrori./ 

/Ploaee ontor aoro than 100 input charactora and wait. . ./ 

8TA&T 



4.10 Determining input characters pending for a line 

This EMT can be used to determine the number of input characters pending for the current line. The 
number of input characters pending is returned in RO. 

The form of the EMT is: 

EMT 375 

with RO pointint to the following EMT argument block: 

.BYTE 1.116 



4.11 Set terminal read time-out value 

This EMT can be used to specify a time-out value that is to be applied to the next terminal input operation. 
This EMT allows you to specify the maximum time that will be allowed to pass between the time that you 
issue a command to get input from the terminal and the time that an activation character is received to 
terminate the input field. You also specify with this EMT a special activation character that is returned 
as the terminating character for the field if the input operation times out without receiving an activation 
cheiracter from the terminal. The form of the EMT is: 



ENT 375 

with RO pointing to the following argument block: 



4.12. TURNING HIGH-EFFICIENCY TERMINAL MODE ON AND OFF 
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.BYTE 0,117 

.WORD time-Talue 

.WORD activation-character 

where time-value is the time-out value specified in 0.5 second units and activation- character is a single 
character value that is to be returned as the last character of the field if a time-out occurs. The time value 
specified with this EMT only applies to the next terminal input field. The time value is reset when the next 
field is received from the terminal or the time-out occurs. A new time-out value must be specified for each 
input field that is to be time controlled. 

Example 



STAET 
1$: 



.TITLE 
DsBonitrati us 
.NCALL 
.TTYOUT 
NOV 
ENT 
.TTYIN 
CMP 
BEq 
CMP 
BEQ 
CMP 
BNE 
•PIINT 
.EXIT 
.BYTE 
.VOEO 
.WO&D 
.NLIST 
.ASCIZ 
.END 



SETTTO , 



DONE 



DUNJUH 

• of ttrMlnal 

.TTYOUT,. TTYIN 

#'T 

«SETTT0.10 

375 

10,i<lE> 
II 

I0,*<12> 

STAIT 

lO.f'Q 

1$ 

iDONE 

0,117 

6*60. *2 

•« 

BEX 

/STOP - / 

STAtT 



Input tlaa-out ttttlng 
,. EXIT,. PRINT 

iPolnt to ENT arg block to 
;Sat toralnal Input tlaa-out 
;Gat a eharactar fron tha terHlnal 
;SlElp OTar carriaga iraturna 

;and Una faada 

;proapt for naxt char 

; Should va quit? 

;No, gat naxt char 

iQult or tlaa-out 

•.Bya 

;ENT arg block 

;6.Bin • 60.Bac/mln 

;ActlTatlon eharactar on tlaa-out 



2.half-aac-nnlt8/Bae 



See also the example program CKTTIE in the section on checking for terminal input errors. 

4.12 Turning high-efficiency terminal mode on and off 

TSX-Plus offers a high- efficiency mode of terminal operation that eliminates a substantial amount of system 
overhead for terminal character processing by reducing the amount of processing that is done on each 
character. When in high-efficiency mode, characters are sent directly to the terminal with minimum handling 
by TSX-Plus; operations such as expanding tabs to spaces and form-feeds to line-feeds are omitted as well 
as input processing such as echoing characters and recognizing control characters such as DELETE, CTRL- 
U and CTRL-C. The only characters treated specially on input are user-defined activation characters and 
the user-specified break character. At least one user specified activation character must be declared if 
high-efficiency mode is to be used. This form of terminal I/O is designed to facilitate high-speed machine- 
to-machine communication. It can also be used effectively to communicate with buffered mode terminals. 
The form of the EMT used to control high-efficiency mode is: 



ENT 



375 



with RO pointing to the following argument block: 

.BYTE code, 120 
where code is 1 to turn high-efficiency mode on and to turn it off. 



Example 
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.TITLE HIEFF 
.KNABL LC 
:Dnonatratt th« utt of TSX-Plui 



STAiT : 



HIEFF : 
TTIBLI: 



TTOBLI : 



BUFFE&: 
BDFSIZ 



DCLCC : 
PEOKPT : 



.NCALL 

• PUNT 

.PlINT 

NOV 

ENT 

MOV 

ENT 



NOVB 

NOVB 

INC 

NOV 

NOV 

ENT 

CLIB 

NOV 

ENT 

.EXIT 

.BYTE 

• BYTE 

.VOED 

.VOID 

.BYTE 

.WOID 

.WOID 

.BLIB 



.EXIT..PEINT 

«DCLCC 

ffPlONPT 

iHIEFF.lO 

S7B 

iTTIBLI.lO 

STB 



Hl-affici«nc7 ttrmlnftl aod* 



chuT 



;Nal[« "C an actiTttlon 
;Aik for input 
;Point to ENT arg block to 
:Turn on hl-offidtncy aodo 
:Polnt to ENT arg block to 
;Acctpt a block of characttra 
; Actual charactor count roturnad In 10 
Do aoaathlng aaaful with tha InputT 
tl6,<BUFFEl-l>(I0) ;laplaca tha actlTatlon char with 
ffl2.BnFFEl(10) :Carrlag« raturn. Una faad 
iO ; Count LF for output 

IO,<TT0BLK'^4> ;8at up count for output 
ffTTOBLI.lO :Point to ENT arg block to 

375 iDlaplay a block of charactara 
HIEFF ;Gat raady to turn hi-aff off 
#HIEFF,10 ;Point to ENT arg block to 

376 :Turn off hl-afflciancy Bodo 



1,120 

0,116 

BUFFEl 

BUFSIZ 

0.114 

BUFFEI 

BUFSIZ 

82. 



. - BUFFER 
.VOiO 
.NLIST 
.ASCII 
.ASCII 
.ASCIZ 
.ENS 



ENT arg block to turn hl-aff soda on (off) 
ENT arg block to ace opt a block of char a 
Polntor to input buffar 
NuBbar of ehara to Input 
ENT arg block to diaplay a block of ehara 
Pointar to buffar for output 
Slza of buffar to output 
I/O buffar — Cannot axeaad lina'a I/O 
buffar aiiaa dadarad in TSGEN 
Spacer in caaa of buffar OTarfill 





BEX 

<S5><'D><S><200> ;Daclara *C aa apacial aetiTation char 

/Plaaao antar 1 Una of charactara ('C onda) ./<16><12> 

/No apacial procaaaing or achoing will ba dona./ 

8TA1T 



4.13 Checking for activation characters 

The following EMT can be used to determine if any activation characters have been received by the line but 
not yet accepted by the program. The form of the EMT is: 

ENT 375 

with RO pointing to the following argument block: 

.BYTE 0.123 

If there are pending activation characters, the carry flag b cleared on return from the EMT; if there are no 
pending activation characters, the carry flag is set on return from the EMT. 

Example 



.TITLE CIACT 

.KNABL LC 
iDeaonitrata naa of chack for actlration charactara 

LEADIN « 36 :T8X-Plua prograa controllad tarmlnal 

;eptlon laad-ln charactor 

.NCALL .PlINT, .EXIT. .OTLIN. .TWAIT. .TTYOUT 
STAIT: .PlINT iPtONPT slaquaat aoaa charactara 



4.14. SENDING A MESSAGE TO ANOTHER LINE 
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;And diaallow dafaned echoing 


;Do ■OM proceB 


ling. Slaulatad 


hor* b7 .TWAIT 




MOV 


«80..11 


;Lin« length counter 


11: 


.TTYOUT 


#'. 


:Tick. tock 




DEC 


11 


;End of llneT 




BNE 


2( 


;No, go on 




•TTYOUT 


#<1B> 


;New line 




• TTYOITT 


«<12> 






MOV 


#80., 11 


;leeot line length counter 


2$: 


.TWAIT 


«A&EA.«TIME 


;Wait 1 eecond here 
Procesiing . . . 




MOV 


fCIACT.KO 


;Point to ENT arg block to 




ENT 


376 


:Check for pending aetiration characters 




BCS 


11 


; Continue if input not coaplete 


• . . . 


.GTLIN 


«BUFFE1 


; Collect the pending input 
Do aoaethlng with It 




CMP 


BUFFEl. EX 


;Exit coaaandT 




BNE 


1$ 


;No, continue proceeelng 




.PlIKT 


fBYE 






.EXIT 






klEk: 


.BLIW 


10. 


;ENT arg block 


TIME: 


.WOLD 


0,l.*fiO. 


;l.eec * eo.tice/aec 


CIACT: 


.BYTE 


0,123 


;EMT arg block for nctlTation char check 


BUFFEl,: 


.BLEB 


81. 


; Local input buffer 




.HLIST 


BEX 






.EVEN 






EX: 


.ASCII 


/EX/ 




PIONPT : 


.ASCII 


<LEADIN>/L/ 


:Dleallov deferred echoing 




.A8CIZ 


/Pleat* *nt«r up to 80 chuactars, fthm lETUlN:/ 


BYE: 


.ASCIZ 


/Thank jou./ 






.END 


STAIT 





4.14 Sending a message to another line 

The following EMT can be used to cause a message to display on another line's terminal. (This feature is 
not related to message communication channels, but is the same as the keyboard SEND command.) The 
form of the EMT is: 



ENT 



375 



with RO pointing to the following argument block: 

.BYTE sub-function, 127 
.WORD lintt-number 
.WORD message-address 

where line-number is the number of the line to which the message is to be sent and meaeage-addrese is the 
address of the start of the message text that must be in ASCIZ form. The message length must be less 
than 88 bytes. Note that if the target screen is only 80 characters wide, characters past column 80 will be 
over\^Titten. If tub-function bit is set and the job issuing this EMT has OPER privilege, then the GAG 
setting of the destination terminal can be overridden. If eub-funetion bit 1 is clear, this EMT waits for a 
free message buffer if none is available. If bit 1 is set and no free message buffer is available, then the EMT 
returns immediately with error code 2. Use of this EMT requires SEND privilege. Note that information 
sent to a line with this EMT is not processed by the window manager for the target line. Thus, if the window 
is refreshed the message sent will disappear. 



Error 
Code 



Meaning 



Job does not have SEND privilege. 

Line has SET TT GAG and is executing a program. 

No free message buffers are available. 
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Example 

See the example program CKSTAT in the section on determining job status information. 

4.15 Starting A Detached Job 

This EMT can be used to start the execution of a detached job. Use of this EMT requires DETACH privilege. 
The process which issues this EMT is known as the parent of the detached job it starts. The form of the 
EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0.132 

.WORD name-address 

where namc-addrees is the address of an area containing the name of the command file to be started as a 
detached job. The command file name must be stored in ASCIZ form and may contain an extension. K a free 
detached job line is available, the specified command file is initiated as a detached job and the number of the 
detached job line is returned in RO. A detached job started by use of this EMT inherits the characteristics 
of the (sub)process that is executing the EMT. IJF there are no free detached job lines, the carry bit will be 
set on return. 

Example 

.TITLE STETDJ 
.BNABL LC 
;8tart a Job en * TSX--P1qs ditachad lint 
CI - 16 
LF > 12 
EI&BTT » 62 

.NCALL .SfTEI,.niTV,. CLOSE,. PRINT,. EXIT 
STA&T: CLt 11 sChuuitl nuabcr 
;No .FETCH !■ nacvtsary ondaz TSX— Plui, huidlart art always rtaldtnt. 
1$: .ENTEl tA&EA, 11, iFILE60.il :Opcn a ona block flla on flrit frat ehannal. 

{Branch on ■ueeaialol .EKTBl 

sVhy didn't .EKTEl work? 

; Error * 1 :not anongh rooa for flla 

;Tr7 naxt highar ehannal 

;Latt ehannalT .CDFIT not aapportod by 

;TSX— PluB, so lagal ehannals ara 0-16. 

;0X, ratry on naxt ehannal 

:lan out of ehannals 

)«CKDEND-C0NND8«l>/2> .iO 
:Bad vritaT 
;Closa tha flla 
iPolnt to EMT arguaants to 
; Start tha datachad Job 
;Bad start of datachad JobT 

iNot anough rooa arror 

:.niTW arror 

iSTlTDJ arror 
;EMT ArguBant araa 





BCC 


21 




TSTB 


•iEllBTT 




BNE 


NOIOON 




INC 


11 




CNP 


ll.ilT 




BLE 


11 




.PlINT 


iNCA 




Bl 


DONE 


2$: .niTV iAlEA.ll.iCONl 




BC8 


WITEU 




.CLOSE 


11 




NOV 


iSTlTDJ.lO 




EKT 


376 




BCS 


OTCHEl 




Bl 


DONE 


NOIOON: 


; .PlIHT 


#NE1 




Bl 


DONE 


VITEU: 


; .PUNT 


iBADVlT 




.CLOSE 


11 




Bl 


DONE 


DTCHEl; 


.PlINT 


iBADDET 


DONE: 


.EXIT 




AlEA: 


.BLIV 


6 
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STITDJ,: .BYTE 0,132 ;EMT arguaenti to itart a detached Job 

.WORD FILNAN :Polnter to name of coMmand file 

.NLIST BEX 

FILIEO:: .lADEO /SY CISTATCON/ :1AD60 name of conmand file to be detached 

FILNAN:: .ASCIZ /8Y:CKSTAT.C0N/ ;ASCII name of conmand file to be detached 

CONNDS:: .ASCIZ /I CISTAT/<1E><12> ; Start a monitoring program 
CNDEND:: 

NEI: .ASCIZ /TSTETDJ-F-Not enough room for command flle./<7> 

NCA: .ASCIZ /TSTRTDJ-F-No channels arailable for command flle./<7> 

BADWIT:; .ASCIZ /TSTITDJ-F-Error writing command fllo./<7> 

BADDET: .ASCIZ /TSTKTDJ-F-Error atartlng detached job./<7> 

.ENS START 



4.16> Checking the status of a detached job 

This EMT may be used to check the status of a detached job. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 



.BYTE 
.WORD 



1,132 

job -number 



where job-number is the number of the detached job to be checked. If the detached job is still active the 
EMT returns with the carry-flag cleared. If the detached job has terminated and the detached job line is 
free, the EMT returns with the carry-flag set. 

Example 



; Check 
START: 

II: 

ABERR: 
STATDJ : 
ABRTDJ; 



ABERN8: 

NOTON: 

EILLED: 



.TITLE 

.ENABL 

■tatua 

.NCALL 

NOV 

BNT 

BCC 

.PRINT 

.EXIT 

NOV 

ENT 

BCS 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.BYTE 

.WORD 

.BYTE 

.WORD 

.NLIST 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



aABDJ 
LC 
of a detached Job and abort It If running 
.EXIT,. PRINT 

iSTATOJ.RO iPolnt to ENT arg block to 
S7E : Check statue of a detached Job 

1< :If atlll on, kill It 

iNOTON ;ElBe. say It len't active 



iABRTDJ.RO 
S7E 
ABERR 
«IILLED 

iABERNS 



; Point to BNT arg block to 

; Abort detached Job 

; Since ve checked, should nerer err 

;Sa7 we killed It 



;ENT arg Talue to check detached Job status 
;Llne number of detached Job to be checked 
:ENT arg Talue to abort a detached Job 
;Llne number of detached Job to be killed 



i.isa 

S. 

2,132 

9. 

BEX 

/TCIABDJ-F-InTalld detached Job number/<7> 

/TCXABDJ-I-No detached Job on line iB/<7> 

/Detached Job on line »9 killed./ 

START 
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4.17 Killing a job 

This EMT may be used to kill any job if the appropriate privileges are present. If it is used to kill a detached 
job, then DETACH privilege is required; to kill primary and secondary lines, DETACH privilege is not 
required. The expected checking is always done for SAME, GROUP, and WORLD privileges. That is: a 
process may always kill its parent or child, may only kill a different line with the same PPN if it has SAME 
privilege, may only kill a process with the same project but different programmer number if it has GROUP 
privilege, and may only kill another job with a different project number if it has WORLD privilege. 

This EMT is equivalent to the keyboard KILL command and checks for DETACH privilege when appropriate. 
The form of this EMT is: 

EMT 37B 

with RO pointing to an argument block like: 

.BYTE 2,132 

. WORD j ob.number 

This EMT may return the following error codes: 



Error 
Codt 



Meaning 



Invalid subfunction code 

Invalid job number 

You do not have privilege to kill that job 



4.18 Establishing break sentinel control 

The following EMT can be used to declare a completion routine that will be triggered when the BREAK 
key is pressed, (Note that receipt of the break sentinel character while the terminal is already in terminal 
input state does not activate entry to the completion routine.) The form of the EMT is: 



ENT 



375 



with RO pointing to the following argument block: 



.BYTE 0.133 
.WORD brkchx 
.WORD cplrtn 

where brkchr is a user defined character that is to be declared the BREAK character and cplrtn is the address 
of the completion routine that is to be called when the break character is received from the terminal. 

The specified completion routine will be called if the user presses either the key labeled "BREAK" (which 
transmits a long space) or types the character that is declared as the user-specified break character (brkchr). 
If no user-specified break character is wanted, specify the value eero (0) for brkchr in the argument block 
and only the real BREAK key will be activated. Note that on some systems the console terminal BREAK 
key causes entry to the hardware ODT module and for this reason cannot be used with thb TSX-Plus 
function. Only one break routine may be specified at a time for each user. If a break routine was previously 
specified, it is cancelled when a new routine is declared. If an address of zero (0) is specified as the address 
of the completion routine {cplrtn), any previously specified break routine is cancelled and the break key 
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connection is cancelled. On return from the EMT, RO contains the address of any completion routine 
previously connected to the break sentinel character. If none was previously connected, then RO will contain 
zero. 

The sp>ecified break completion routine request only remains in effect for one break character. If you wish to 
be notified about additional break characters, you must reestablish the break connection each time a break 
character is received. This can be done from within the break completion routine. 

A break routine can be used to signal an asynchronous request for service to a running program. A good 
example of this use would be to trigger entry to an interactive debugging program. 

Exairiple 



.TITLE BllSNT 
;Dnio nit of braak ••ntin«l control 



8TA1T : 



DONE: 
CNPITN; 



BUSNT : 



fES: 

AiEA: 

TIME: 



NESSAG: 
60TBU : 
NOBU: 



.NCALL 

.ENABL 

NOV 

ENI 

.PIINT 

•TWAIT 

TST 

BNE 

.PIINT 

.EXIT 

.PIINT 

MOV 

tETUlN 



.BYTE 
.WOEJ) 
.WO&O 

.WOU) 

.BLIW 

.WO&O 

.WO&D 

.NLI8T 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



.PIINT,. TWAIT,. EXIT 

LC 

iBUSNT.tO 

376 

iKBSSAG 

iA&EA.tTINE 

YES 



DONE 
iNOBU 

«GOTB&I 
ffl.YES 



0,133 



CMPaTN 



; Point to arguBont arta to 

;Eitabliih break atntlnal control 

;Proapt for k«7 

;G1to the oaor 2 ■oconda to hit tho break kay 

:ETtr ata a braakT 

;Ta>, all dona 

;No, noTar tav it 



Say wa caught tha braak 

lemaHbar it 

And continue 

Coaplation routinaa ara ALWAYS axLtad with 

ITS PC undar TSX-Plua, NEVEi -ria ITI 

ENT arg ralua block to braak aantinal control 

Daclara only 'B&EAK' kay aa braak char 

Addrati of eoaplation routine to be called 

when ayatea noticea break 

Flag for break aeen 

.TWAIT 



2 word arg area for 
high word of tlae 
a aee • 60.tica/Bee 





2 



2.*60. 

BEX 

/You hare 2 aeconda to hit the break key./ 

<16><12>/Break key preaaed./ 

/NeTor aaw the break key./ 

STAftT 



\index'(TerBlnal ; Input coHpletion routine} 
Mndex'CCoapletlon routine; Terminal input> 
\aecti<oin{Terminal input completion routine} 

The following EMT can be uaed to apecify a completion routine which 
will be triggered when tha next character ia entered at the terminal. 
The form of the EMT ia: 
\begln{Terbatim} 
EMT 376 

with RO pointing to the following argument block: 



.BYTE 
.WOU) 



1,133 
completion-routine 



where completion-routine is the address of the completion routine to be entered when the next character is 
typed. 

On entry to the completion routine, the received character is in RO. The EMT to connect the completion 
routine must be rescheduled before returning if it is desired to continue accepting characters via the com- 
pletion routine. The program should be running with single character activation and bit 12 set in the job 
status word. 



Exannple 
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JSV 

TTSPCI 
TItLC 
SPACE 
8TA1T : 



.TITLE TTICPL 
Draonttrat* ttrmlnal ch&rKcttr input coiqilctlon rootinc. 
.ENABL LC 
CBL 

PtTOEC 
.ITTOOT..SPND,.P1INT 

Job Statai Word addrtii 
TT •ptcl&l Bodt (slnglo char input) 
Bnablt lovor caao bit 
ASCII Spaca 
fTTtLC! TTSPCI. if JS¥ ;Sat ainglo charactar soda 



CPLRTN: 



TTICPL; 



C&LF: 



.DSABL 
.6L0BL 
.NCALL 

- 44 

« 10000 
. 40000 

- 40 
BIS 
NOT 
ENT 

.SPND 
NOV 

.TTTOUT 

.TTTOW 

NOT 

CALL 

.PUNT 

NOT 

ENT 

lETUlN 

.BYTE 

.WOIO 

.A8CIZ 

.END 



iTTICPL.lO 
378 

10. -(SP) 

fSPACE 

(SP)-^,10 

PITDEC 

iClLF 

fTTICPL.lO 

376 

1,133 
CPLtTN 
II 
STAIT 



-.Point to ENT arg block to 

:Schedula TT input char coapl routina 

;8uipand main-lino (forarar in axampla) 

;SaTa input char carriad in 10 

;Echo tha char 

;latri ara char 

iDiaplay ita ASCII valua 

;Point to ENT arg block to 

;8chadula TT input char coapl routina 

;EMT arg block for TT input eompl routina 
;Coiq>lotion routina to run 



4.19 Mount a file structure 

This EMT is used to tell TSX-Plus that a file structure is being mounted and that TSX-Plus should begin 
caching the file directory for the device. The effect of this EMT is the same as doing a system MOUNT 
keyboard command to enable caching. It cannot be used to mount a logical subset disk. The form of the 
EMT is: 



ENT 



375 



with RO pointing to the following argument block: 

.BYTE 0.134 

.WORD device-Bpec-addresB 

.WORD 

where dcvtee-epec-addreaa is the address of a word containing the RAD50 form of the name of the device on 
which the file structure is being mounted. If there is no room left in the table of mounted devices, the carry 
bit is set on return and the error code returned is 1. 

Example 



.TITLE NDUNT 

.ENABL LC 

; Daaonatrata T8Z--Plua ENT to NOUNT (do diractory caching on) a darica 

.6L0BL IftAD60 jSTSLIB IAD60 conroraion aubroutlno 

BS ■ 10 : ASCII Backtpaea 

.NCALL .P1IKT,.0TLIN,.EXIT 

STAiT: .6TLIN f BUFFEl . fPiOKPT :Aik for naaa of dOTlca 

NOT ilBOBLI.IE ; Point to arg block for naxt call 

CALL IIADBO ;ConTart ASCII darlca naaa to 1AD60 

NOT f NOUNT, 10 :Point to ENT arg block to 

ENT 376 ;Nount a fila atructura (dlractory caching) 

BCC 8TA1T :Aak for aora if 01 
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.paiNT 


fNOGOQD 




.EXIT 






.NLIST 


BEX 


MOUNT: 


.BYTE 


0,134 




.WOU) 


DEVNAN 




.VOID 





160BLI: 


.VOID 


3 




.VOID 


TH&EE 




.WORD 


BUFFE& 




.VO&O 


DEVNAN 


THUKK: 


.WOiJ) 


3 


CEVNAN:: 


.VOBJ) 





EirFFEt: 


.BLEB 


80. 


PEOMPT ;; 


.ASCII 


/Nam* of 


NOGOOD; 


.ASCIZ 


/Atttmpt 




.END 


STAKT 



;Sa7 it vaa not good 



:ENT arg block to Mount « fil* Btructuro 

;Pointor to IAD60 nam* of drrlca 

;lequlr«d argimont 

:NuMb«r of argt for I1AD60 call 

;Pointer to nuBbar of chart to eonrtrt 

;Polnttr to chars to conTtrt 

;Polnttr to 1AD60 naao of doTlct 

;Niuber of chart to conTtrt 

:1.AD50 rtprttontation of derlct naae 

;GTLIN input bufftr 

dtrico to b« Mounted: :/<BS><BS><BS><BS><200> 

to MOUNT too Many deTlcot./<7> 



4.20 Dismount a file structure 

This EMT can be used to tell TSX-Plus to stop doing directory caching on a particular drive. The effect of 
this EMT is the same as a DISMOUNT keyboard command to disable caching. The form of the EMT is: 

EMT 375 

with RO pointing to an argument block of the following form: 

.BYTE 0,135 

.WORD deTice-spec-address 

.WORD 

where device-spcc-addresB is the address of a word containing the RAD50 name of the device to be dis- 
mounted. 

Exannple 



.TITLE DISNNT 
.ENABL LC 
DtMonttratt TSX— Plut EMT to DISMOUNT (stop caching on) a dtTlco 



BS 



STAET: 



DIS^[NT 



t60BU:: 



THREE;; 
DEVNAH 
BUFFEll 
PlOMP^r 



.GLOBL liADBO 

. 10 

.NCALL .6TLIN 

.6TLIN «BUFFEB,,«PIONPT 

NOV «EEOBLI.&S 

CALL lEADEO 

MOV f DISNNT, 10 

BNT 37B 

BE STAET 

.NLIST BEX 

.BYTE O.ISB 

.ffOED DEVNAN 

.WOED 

.VOED 3 

.WOED THESE 

.VOED BUFFEE 

.VOED DEVNAN 

.VOED 3 

.VOED 

.BLIB 80. 

.ASCII /NaMO of dtTlct to b* dltMounttd 

.END STAET 



;SYSLIB EAD60 conrtrtion tubroutina 
; ASCII Backtpaca 

;Aak for naMt of dtirlet 

;Polnt to arg block for next call 

; ConTtrt ASCII dtTiet naMt to EADBO 

:Polnt to ENT arg block to 

;diaMount a flit atructurt (itop caching) 

:Etptat (no trrort rtturntd) 

;ENT arg block to diiMount a flit atructurt 

;Pointtr to EAD50 ntMt of dtTlct 

;Etqulrtd arguMtnt 

:NuMbtr of argt for IEAD60 call 

;Pointor to nuMbtr of chart to conTtrt 

;Polnttr to chart to conTtrt 

;Polnttr to EAD60 niMO of dtTlct 

:NuMbor of chart to conTtrt 

;EAD60 rtprtatntatlon of dtTlct naMt 

iGTLIN Input bufftr 

: /<BS><BS><BS><BS><200> 
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4.21 Dismounting all file structures and logical disks 

This EMT can be used to dismount all file structures for the job from directory and generalized data cache. 
This dbmounts all logical disks from cache as well as cached physical disks. Note that this simply removes 
all logical disks from the cache tables; the logical disks are still accessible. Also note that issuing the SHOW 
SUBSETS (also SHOW LD) command will cause the logical disks to be cached again. The form of the EMT 

is: 

EMT 375 

with RO pointing to an argument block of the following form: 

.BYTE 2.135 
.WORD 

Example 

.TITLE DKTFLS 
.EN&BL LC 

Dnonitratt ENT to dlMouiit (atop caching on) all fllaa itructurti. 

.HCALL .P1INT..EXIT 
.DSiBL GBL 

EIRBYT - 62 :EMT orror b^tt addrtta 

STAtT: NOT fDNTFLS.tO ; Point to ENT arg block to 

ENT 376 :Dl»ount all Xllt atractaroi 

BCC 91 ; Branch If 01 

.PUNT ffENTEU ;"irnablt to dlsBoont all fllas •tructaroa" 
0(: .EXIT 

DNTFLS: .BTTE 2,136 :ENT arg block to dltBount filo atmctaroa 

.WOID 

.NLIST BEX 

ENTEU: .ASCIZ /TDNTFLS-F-Onablt to dlaaonnt all flloa atraetoraa/ 
.EVEN 

.END 8TA1T 



4.22 Dismounting Logical Disks 

The following EMT can be used to dismount a logical disk. The form of the EMT is: 

ENT 375 

with RO pointing to the following argument block: 

.BYTE 3,135 
.BYTE Id-unit. 

where Id-unit is the logical disk unit number which must be in the range to 7. 
The following error codes can be returned by this EMT: 
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Error 
Code 



Meaning 



Specified LD unit is not associated with a file 
Invalid LD unit number (must be in the range to 7) 
Some channel is opened to a file on the logical disk 



Example 



.TITLE Dh(NTLD 



;Deaonntratlon of the ubs of the TSX-Plui ENT to diemount a logical dlik. 



EULBYT - 



STUT: 



1$: 



21: 



SNTLDE: 



DNTLD0 : 



EUIS: 



.NCALL 


.PRINT.. EXIT.. ( 


:lose 


.6L0BL 


P&TDEC 




.DSABL 


GBL 




- 62 




;ENT orror byt* addr«Bt 


NOV 


iDNTLDB.lO 


; Point to ENT arg. block to 


ENT 


S7B 


;Di amount LD6: 


BCS 


11 


;Branch if not 01 


NOV 


«DNTLD6.10 


;Point to ENT arg. block to 


ENT 


S7E 


;DiaMount LD6: 


BCC 


2$ 


{Branch If 01 


NOVB 


f#RRRBYT.-(SP) 


;Fetch ENT arror cod« 


.PEINT 


«RRRIS 


:"ENT arror la:" 


NOV 


(sp)+.ao 


;RatriaTa arror coda 


CALL 


PRTDEC 


{Display it 


.EXIT 






.NLIST 


BEX 




.BYTE 


3.1SB 


:ENT arg. block to diamount 


.BYTE 


E.O 


:LDE: 


.BYTE 


S.ISE 


;ENT arg. block to dismount 


.BYTE 


«.o 


;LD6: 


.ASCII 


/TDNNTLD-F-ENT 


arror is: /<200> 


.EVEN 






.END 


START 





4.23 Determining Status of Logical Disks 

The following EMT can be used to provide the status of a LD unit. The form of this EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 4,135 
.BYTE Id-unit. 
.WORD buffer-address 

where Id-unit is the LD unit number in the range to 7, and buffer-addreas is the address of a five-word 
buffer which will receive information about the logical disk. 

If the logical disk is not associated with a file then all zeros will be stored into the buffer If the LD is 
associated with a file, the first four words of the buffer will receive the RAD50 device name file name (2 
words), and extension. The fifth word is a flag word. If the LD is mounted for read-only access, bit of the 
flag word is set. If the LD is not currently accessible, bit 1 is set. 
The following error code can be returned by this EMT: 
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Error 
Code 



Meaning 



Invalid LD unit number (must be in the range to 7) 



Example: 



.TITLE LDSTAT 

.HCALL .PEINT. .EXIT, .LOOIUP, .8PFUN, .CLOSE, .SEU. .HEIl 

.CLOBL P&TOCT,PRT&BO,P1TDEC 

.DSABL GBL 



ST AIT : 


CLl 


LDTOIT 


: Start vlth LDO 


1$: 


CKP 


LDUNIT, tr 


;HaT« w« print info on all LD'i 




BGT 


01 


; Branch it not 




.PtINT 


fLDPlT 


;Sp«cifT LD nuabor 




MOV 


LDUNIT, 10 






CALL 


PITDEC 






.PlINT 


iCOLEQU 






MOV 


iLDSTAT.lO 


;Sat up to. . . 




ENT 


S7B 


;G«t atatui for thia LO 




BCC 


2$ 


:Branch if O.E. 




.PlINT 


ffOOPS 


;ElBa "LD Statua ENT Error" 




BI 


0( 


;And giva np 


31: 


CLE 


SIZE 


;AaBuat not aountad 




NOV 


«BUFF,11 


;6at buffar addraia 




NOV 


(11)^.10 


;Got DotIco naaa 




BEQ 


011 


;B1 if not Bountod 




IHC 


SIZE 


;laBaab«r to gat aiia 


21$: 


CALL 


P1T160 


; Print daTlca naaa 




.PlINT 


fCOLON 


.n .n 




NOV 


(11) +.10 


;6at firit half of fila naaa 




CALL 


PlTl&O 


;Print it 




NOV 


(11) +,10 


:Gat laat half of fila najia 




CALL 


P1T160 


-.Print it 




.PUNT 


«DOT 


. n n 




NOV 


(11)+. 10 


;Got axtanaion 




CALL 


PITISO 


: Print it 




.SEll 




;Trap Error a 




NOVB 


LDUNIT, 10 


:6at DoTica and unit mmbar 




iOD 


f'-lLD0,10 






NOV 


lO.DEV 






.LOOIUP 


*AlEA,f0.iDEVSPC ;Op«n a chuuitl to it 




BC8 


31 


; Branch on arror 




.SPFUN 


fAlEA.fO.tSrS 


iSIZE.tl.ffl ;Gat tha aiia of LD 




BCS 


3$ 


;Branch on arror 




.PUNT 


fLSQBl 


;"[" 




NOV 


SIZE, 10 


:6at tha aiia 




CALL 


PlIDEC 


;and print it 




.PUNT 


fflSQBl 


•" .]" 


SI: 


.REll 




;laport arrora 




.CLOSE 


«0 


;Cloia tha channol 


41: 


.PUNT 


fSTAT 


:" STATUS" " 




NOV 


(11) +.10 


;Gat tha atatna 




CALL 


PITOCT 


;and print it 




.PUNT 


•CILF 


iFiniah tha lina 




Bl 


92$ 




911: 


.PUNT 


•NOTFfNT 


:"Not Bonntad" 


92t: 


INCB 


LDUNIT 


:IncraBant LD unit mmbar 




Bl 


11 


: Print info, on naxt LD 


01: 


.EXIT 







LDSTAT: .BYTE 4.136 
LDUNIT: .BITE 0,0 
.VOID BUFF 



;Argiuitnt block for ENT gat LD atatua 
;LD unit nuBbar 
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;Ar«a vhara stfttut Info, is put 
LOOIUP ENT block 



BUFF: 


.BLIW 


5 ;Ar«a 


AiEA: 


.BLIV 


10 :AT*a 


DEV: 






DEVSPC : 


.1AD60 


/LDO/ 




.WOLD 


0,0,0 


SIZE: 


.WORD 





COLON: 


.ASCII 


/:/<200> 


DOT: 


.ASCII 


/./<200> 


STAT: 


.ASCII 


/ STATUS= /<200> 


LDPiT : 


.ASCII 


/LD/<200> 


COLEQU: 


.ASCII 


/: - /<200> 


CILF: 


.ASCIZ 


// 


LSQBl: 


.ASCII 


/[/<200> 


ISqBI: 


.ASCII 


/.]/<200> 


OOPS: 


.ASCIZ 


/LD Status ENT Error/ 


NOTNNT : 


.ASCIZ 
.EVEN 


/Not Bountcd/ 




.END 


STAiT 



4.24 Dismounting all logical disks 

The following EMT allows dismounting of all logical disks with one EMT. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 5.135 
.WORD 

The following error code can be returned by this EMT: 



Error 
Code 



3 



Meaning 



Some channel is opened to a file on the logical disk. 



This EMT is similar to the SET LD EMPTY command. All LD's are completely dismounted, and become 
inaccessible until remounted. This is unlike the EMT to dismount all files structures which simply removes 
file structures from the caching tables. 

Example 





.TITLE 


DNTALD 






.ENABL 


LC 




Dnionatrat* 


ENT to dlBBOUnt 


all logical diaka. 




.NCALL 


.PRINT,. EXIT 






.6L0BL 


PITDEC 






.DSABL 


GBL 




E&iRTI 


- 62 




:ENT error byta addrasa 


STAtT : 


NOV 


«DNTALD,10 


;Polnt to EMT arg block to 




EMT 


S7E 


;DliMount all logical dlaka 




BCC 


9% 


;Branch if OX 
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NOV 



•♦ElEBYT , - (SP) ;Pttch EHT •rror code 



.P&IKT *ENTESA 

MOV (8P)+.lO 

CALL PITDEC 
91 : .EIIT 

DHTALD: .BYTE 6.1SB 

.WORD 



;"nnabl» to diiMount all logical dlaka. Error" 
;IotT«lTa arror coda 
;And print it 

;ENT arg block to dlamount all logical dlaka 



.HLIST BEX 

EHTERl: .ASCII /TDMTALD-F-Unabla to diamount all logical diaka . Error: /<200> 

.EVEN 

.END STAET 



4.25 Determining the terminal type 

The following EMT will return in RO a value that indicates what type of time-sharing terminal is being used 
with the line. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,137 

The terminal type is specified either when the TSX-Plus system is generated or by use of the SET TT 
command (e.g., SET TT VTlOO). The terminal type codes which are currently defined are listed below. 
The types Diablo and Qume are functionally equivalent. 



Terminal-type 


Code 


Unknown 





VT52 


1 


VTlOO 


2 


Hazeltine 


3 


ADM3A 


4 


LA86 


5 


LA120 


6 


Diablo & Qume 


7 


VT200 


9 



A type code of zero (0) is returned if the terminal type is unknown. 

Example 

See the example program LNTT in section 4.4 on determining the TSX-Plus line number. 



4.26 Controlling the size of a job 

Under RT-11, the .SETTOP EMT is used to set the top address of a job. The TSX-Plus .SETTOP EMT 
does not actually alter the memory space allocated to a job but simply checks to see if the requested top of 
memory is within the region actually allocated to the job and if not returns the address of the top of the 
allocated job region. The TSX-Plus .SETTOP EMT was implemented this way because many programs 
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written for RT-11 routinely request all of memory when they start regardless of how much space they 
actually need. 

The memory space actually allocated for a job can be controlled by use of the MEMORY keyboard command 
or by use of the EMT described below. The memory size specified by the most recently executed MEMORY 
keybojird command is considered to be the normal size of the job. The EMT described here can be used to 
alter the memory space allocated to a job but the job size reverts to the normal size when the job exits or 
chains to another program. 

The form of the EMT used to change a job's size is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 0.141 
.WORD top-address 

where top-addrese is the requested top address for the job. If this address is larger than the allowed size of a 
job, the job will be expanded to the largest possible size. On return from the EMT, RO contains the address 
of the highest available word in the program space. 

A program is not allowed to change its size if it was started by use of the RUN/DEBUG command or the 
system was generated without allowing program swapping. In either of these cases the EMT operates exactly 
like a .SETTOP request (i.e., the requested program top address will not be allowed to exceed the normal 
program size). 

See also the description of the SETSIZ program in Appendix A for information about how the default 
memory allocation for a program can be built into the SAV file for the program. 

Example 

See the example program CKSTAT in section 4.27 on determining job status information. 

4.27 Determining job status information 

The information about various jobs on the system which is displayed by the SYSTAT command may also be 
obtained by application programs. An EMT is provided with several subfunctions to obtain the desired job 
status! information. This EMT may obtain information about any job on the system, not only itself. The 
form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,144 

.BYTE line-#, sub-function 

.WORD buf -address 

where line-# is the number of the time-sheiring line about which information is to be returned. Line numbers 
are in the range 1 up to the highest valid line number for the system. Sub-function is a function code which 
indiciktes the type of information to be returned by the EMT (see below), Buf-addrest is the address of the 
first word of a 2-word buffer area into which the returned value is stored. Note: some of the functions only 
return a single word value in which case the value is returned into the first word of the buffer area. 

If an error occurs during the execution of the EMT, the carry-flag is set on return and the following error 
codes indicate the type of error: 
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Error 
Codt 



Meaning 



Indicated line number is not currently logged on. 

Invalid sub-function code. 

Invalid line number (0, or higher than largest valid line number). 



Each of the sub-functions is described below: 

Subfunction # Check status of line. The value returned contains bit flags that indicate the status of 
the job. The following bit flags are defined: 



Bit Flags 


Meaning 


000001 
000002 
000100 
000200 


This is a subprocess. 
This is a detached job line. 
Job has locked itself in memory. 
Job has SYSPRV privilege. 



Subfunction # 1 Get job's execution state. This subfunction returns a code that indicates a job's current 
execution state. The following code values are defined: 



Code 


Meaning 


1 


Non-interactive high priority run state. 


2 


Normal priority run state. 


S 


Fixed-low-priority run state. 


4 


Waiting on input from the terminal. 


5 


Waiting for output to be written to terminal. 


6 


Doing A timed wait. 


7 


Suspended because .SPND EMT done. 


8 


Waiting for access to a shared file. 


9 


Waiting for a inter-job message. 


10 


Waiting for access to USR (file management) module. 


11 


Waiting for non-terminal I/O to finish. 


12 


Waiting for access to spool file. 


13 


Interactive high priority run state. 


14 


Fixed-high-priority run state. 


15 


Waiting for memory expansion. 



Subfunction # 2 Determine amount of memory used by job. This function returns the number of 256- 
word blocks of memory that are currently being used by the job, including PLAS regions. 

Subfunction # S Determine connect time for job. This function returns the number of minutes that a job 
has been logged onto the system. 

Subfunction # 4 Determine position of job in memory. This function returns the 256-word block number 
of the start of the memory area allocated to the job. 

Subfunction # 6 Get name of program being run by job. This function returns a 2-word value. The two 
words contain the RAD50 value for the name of the program currently being run by the job. 

Subfunction # 6 Get project and programmer number for job. This function returns a two-word value. 
The first word contains the project number that the job is logged on under; the second word contains 
the programmer number. 

Subfunction # 7 Get CPU time used by job. This function returns a two-word value that contains the 
number of clock ticks of CPU time used by the job. The first word contains the high-order 16-bits of 
the value, the second word contains the low-order 16-bits. 
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Subfunction # 8 Get current job execution priority This function returns one word that contains the 
current job execution priority level (0-127). 

Subfunction # 9 Get job name for the specified line number. The return buffer must be at least 12 bytes 
long. 



Example 



.TITLE 

.ENABL 
; DcHon strati on 
EBJJ3YT = 62 
P&GNAN s B 

.NCALL 
START: MOV 

ENT 



CISTAT 

LC 

of MEMTOP, 



JSTAT and SNSNSG EMTa of TSX— Plui 
;ENT arror coda location 
; JSTAT aubf unction coda to gat prog. 



.TWAIT,.EXIT 

*NENT0P,EO 

S7E 



;Polnt to ENT arg block to 
;Sat job alia 



;0nl7 trorka in avapplng anTironmant, otharwiaa bahavaa Ilka .SETTOP 

CKP EO.iHILIN ;Saa if wa got what wa wantad 

BHIS AGAIN :Go on if ao 

.EXIT ;alaa quit (cannot dlap arr mag from dat Una) 

AGAIN: NOVB ffl.LINE ;Chack all linaa atasrting with «1 

CHECK: NOV iJSTAT.KO :Polnt to ENT arg block 

ENT 376 ;Get naaa of job balng run 

BCS EUTYP ;Go find out what kind of arror 

CKP BUFADD.DUNJUN :Ib this Una goofing offT 

BNE NEXT ;No, procaad 

CNP BUFADD-»2.DirNJDN-»2 ;Na7 ba, ehack for aura 

BNE NEXT :No, procaad 

;Sand n aasaaga to tha offanding Una 

: (Each Baaaaga muat ba < 88. bytaa) 



NEXT: 



SLEEP: 



EUTYP: 



ai: 

NENTOP: 

JSTAT: 

LINE: 

SUBFUN: 

BUFADD: 
NAXLIN: 



NOVB 

NOV 

NOV 

ENT 

NOV 

NOV 

ENT 

NOV 

NOV 

ENT 

NOV 

NOV 

ENT 

INCB 

CNPB 

BGT 

Bl 

•IWAIT 

Bl 

CNPB 

BLT 

BEQ 

NOVB 

DECB 

Bl 

.EXIT 

.BYTE 
.WOID 
.BYTE 
• BYTE 
.BYTE 
.WOID 
.BLEW 
.BYTE 
.EVEN 



LINE.YOOHOO 

*NESAG1.NSGADD 

ff SEND, 10 

375 

*NESAG2,NS6ADD 

ffSEND.lO 

376 

9NESAG3.NSGADD 

iSEND.lO 

376 

iNESAG4.NSGADD 

»SEND,10 

376 

LINE 

LINE, NAXLIN 

SLEEP 

CHECK 

fAlEA,«TINE 

AGAIN 

f«E&lBYT,#l 

NEXT 

2t 

LINE, NAXLIN 

NAXLIN 

SLEEP 



0.141 

HILIN 

0,144 



PIGNAN 

BUFADD 

2 

30. 



Who la tha guilty partyT 

Prapara part ona of Maaaaga 

Point to ENT arg block to 

Sand a aaaaaga to that Una 

Prapara for part two of tha aaaaaga 

Point to ENT arg block to 

Sand part 2 of aaaaaga 

Prapara for part thraa of tha aaaaaga 

Point to ENT arg block to 

Sand part S of aaaaaga 

Prapara for part four of tha aaaaaga 

Point to ENT arg block to 

Sand part 4 of aaaaaga 

Try naxt Una 

HaTO wa ehaekad thaa allT 

Taa, wait awhila 

Go chaek tha raat of tha linaa 

Coaa back in 6 alnutaa 

And try again 

Which arror la it 

— > Una not loggad on, try naxt Una 

1 — > inralld aub-f unction coda, glTa up 

2 — > Una > laat ralid Una 
Largaat valid Una nuabar 
ahould only happan firat tlaa 
InTalld coda ahould noTar happan 
Night aa wall kill job 
Arguaant block for MENTOP ENT 
Oppar addraaa Halt 

Arguaant for JSTAT ENT 

TSX-Plua Una nuabar to ba ehaekad 

ENT aubfunction 

Addraaa of 2-word buffar for ratnrnad Talua 

2 word buffar to hold atat raault 

Naxlaua nuabar of linaa undar TSX — Plua 

Will ba altarad to aax Talid Una f 
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SEND: 


.BYTE 


0.127 


:EKT arg block to ttnd a atatftgo 


YOOHOO: 


.VOID 





;Dtttlnatlon Una niwbar 


NSGADD : 


.VOID 


HE8AG1 


;Naaiaga to ba aant 


ALEA: 


.BLIV 


2 


;.TVAIT arg araa 


TIME: 


.VOID 





;tlaa high word 




.VOID 


6*60. •60. 


:6aln • eo.iac/aln « 60.ticki/aac 




.KLIST 


BEX 




DOHJTO: 


.1AD60 


/DUHJDN/ 


;NaBe of illicit program 


NESAGl: 


.ASCII 


<T><1B><12> 






.ASCII 


/•««*«*«•**««*•*•*•«**** •«***»*«***/<16><12> 




.ASCIZ 


/• 


•/<1B><12> 


NESAG2: 


.ASCII 


/• Continued utt of thii •yatn •/<16><12> 




.ASCIZ 


/• lor (ABO 


playing will raault */<lB><12> 


NESAGS: 


•ASCII 


/• In loit 


ol uaar prlTllagaa!! •/<1B><12> 




.ASCIZ 


/* 


*/<lB><12> 


NESAG4: 


.ASCIZ 


/«««*«««***«it***«*««*««***«***«*««*/<lS><12><7> 


HILIN: 


.END 


STA&T 





4.28 Determining file directory information 

This EMT returns directory information about a file. The form of the EMT is: 



EMT 



375 



with RO pointing to the following argument block: 



.BYTE Chan, 145 
.WORD dblk 
.WORD Tblk 



where chan is a channel number in the range 0-16 (octal) that is currently not in use, dblk is the address of 
a 4-word block containing the RAD50 file specification (device, file name, extension), tind rhlk is the address 
of a 7-word block that will receive the information about the file. The information returned in rblk is: 



Word Number 


Meaning 


1 


Size of the file (number of blocks) . 


2 


0=File not protected; l=File is protected. 


8 


File creation date (standard RT-11 date format). 


4 


File creation time (number of 3-second units). 


5 


Starting block number of file. 


6 


Unused (reserved) 


7 


Unused (reserved) 



Error 
Code 



Meaning 



Channel is currently in use. 
Unable to locate specified file. 
Specified device is not file structured. 



Example 



4.29. SETTING FILE CREATION TIME 
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.TITLE FILINF 
.ENABL LC 
; Deaonttratc TSX--Plui ENT to return Infonutlon about a file 
.MCALL .PEINT, .EXIT, .CSISPC, .TTYOUT 
DSPDAT.DSPTIS.P&TDEC 

;ENT arror cod* location 
iOUTSPC,«DEFLT.»0,«BUFFER ;G*t fll« nana 



EEIBYT 
STA&T: 



6<: 

10$: 



1B$! 



FILINF: 



FILSIZ 
PtTCTD 
FILDAT 
FILTIN 
FILLOC 

OUTSPC 
INSPC 
DEFLT 
FIEU 



BUFFEl 
SPACE2 
CINTJSE 
NOFILE 
BADDEV 



.GLOBL 

= 62 

.CSISPC 

NOV 

ENT 

BCC 

NOVB 

ASL 

.PEINT 

.EXIT 

NOV 

TSTB 

BNE 

NOVB 

.PEINT 

.TTYOUT 

NOV 

CALL 

TST 

BEQ 

.TTYOUT 
.TTYOUT 
.PEINT 

NOV 

CALL 
.PEINT 

NOV 

CALL 
.PEINT 

NOV 

CALL 

.EXIT 

.NLIST 

.BYTE 

.WOED 

.WOED 

.WOED 

.VOED 

.WOED 

.WOED 

.WOED 

.WOED 

.BLIW 

.BLEW 

.WOED 

.WOED 

.WOED 

.WOED 

.BLEB 

.ASCII 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



:Polnt to ENT arg block to 

;Gat Information about a file 

;No orrorT 

;What error 

;ConTert to word index 

■.Explain It 

;Flnd the end of the file epoc, 

:EndT 

;No, keep looking 

:No CE.LF at end 

;F11* nase 

:Flle else 

;Waa file protected? 



;Flle creation date 
;Dlapla7 date 

;Flle creation tlae (9 eec reaolutlon) 
;DlBplaj apeclal S-aec tlM* 

:Flle starting block « 



:ENT arg block to get file Info. 
;Polnter to EAD60 file naae 
iPolnter to 7 word result buffer 
:F11* slse 

;Protectedsl, unprotected=0 
;Flle date (standard format) 
;Flle time (special S-s*e format) 
;Flle starting block number 
;Pad for 2 res erred words 
; Output file specifications 
; Input file specifications 
:No default extensions 
;ENT error message table 



iFILINF.EO 

376 

6( 

•«EEEBYT,E1 

El 

FIEEE(El) 

ffBUFFEE.EO 

(E0) + 

10$ 

#200, -(EG) 

iBUFFEE 

#■[ 

FILSIZ, EO 

PETDEC 

PETCTD 

16$ 

• •P 

#'] 

iSPACE2 

FILDAT. EO 

DSPDAT 

fSPACE2 

FILTIN. EO 

DSPTI3 

*SPACE2 

FILLOC, EO 

PETDEC 

BEX 

0,146 

INSPC 

FILSIZ 











0,0 

16. 

24. 

0.0,0,0 

CINUSE 

NOFILE 

BADDEV 

81. 

/ /<200> 

/TFILINF-F-Channel In use./ 

/TFILINF-F-Can't find file./ 

/TFILINF-F-Non-dlrectory derlce./ 

8TAET 



; Input string buffer 



4.29 Setting file creation time 



The time that a file is created is stored along with other directory information under TSX-Plus. In order 
to pack the time into a single word, TSX-Plus represents the file creation time in three second units. For 
example, if a file was created at 11:13:22, then the special time representation would be 13467 (decimal). 
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11 hr 



60 min/hr 
IS min 



60 sec/min 
60 sec/min 
22 sec 



89600 sec 

780 sec 

22 sec 

40402 sec 



18467 S-sec units 



A utility program is provided with TSX-Plus to display the creation time and other directory information 
about a file. See the TSX-Plut Uttr't Reference Manual for more information on the FILTIM utility. 
The creation date and time for a file are automatically stored by TSX-Plus in the directory entry for the 
file at the time that the file is closed after being created. An EMT is provided for those unusual situations 
where a different creation time is to be specified for a file after the file is created. The form of this EMT is: 



ENT 



375 



with RO pointing to the following argument block: 



.BYTE Chan. 146 
.WORD dblk 
.WORD time 

where chan is the number of an unused channel, dblk is the address of a 4-word block containing the RAD50 
file specification, and time is the time value (in 8-8econd units since midnight) that is to be set as the creation 
time for the file. 



Error 
Code 



Meaning 



Channel is currently in use. 
Unable to locate specified file. 
Specified device is not file structured. 



Example 





.TITLE 


SFTIN 




.ENABL 


LC 


: DMonstratt ISX— Plui EMT to 




.MCALL 


.PUNT,. CSISPC, 




.GLOBL 


ACITI3 


E&EBTT 


* 62 




STA&T : 


.PlIHT 


ffGETNAN 




.CSISPC 


•OUTSPC.ffDEFLT 




.GTLIN 


iBUFFEl.*GETTIN 




NOV 


•BDFFEI.IO 




CALL 


ACITIS 




BCC 


11 




.PIIKT 


fBADTIN 




.EXIT 




It: 


NOT 


lO.NEVTIN 




NOT 


•SFTIN. 10 




ENT 


976 




BCC 


2( 




NOVB 


•tEUBYT,IO 




A8L 


10 




.PlINT 


SFTElldO) 


2$: 


.EXIT 






.NLI8T 


BEX 


SFTIM: 


.BYTE 


0.140 




.VOID 


INSPC 


NEWTIN: 


.VOID 






■It flic crtation tiaa 
.EXIT.. GTLIN 

Subroutina to conTort hh :■■:■■ to ■poel&l 

S-ioc intornal tlsa format In 10 

ENT arror coda location 

Prompt for fila nama 

Gat fila nama in 1AD60 

Prompt for and gat a tiaa 

Point to tiaa input buffar 

Gat apecial tima in 10 

Tima arrorT 

Toa. Incorract format 

;8aTa apacial tima 

:Point to ENT axg block to 

:Sat eraation tiaa in fila 

:ErrorT 

;Taa. gat arror coda 

;ConTart to word off a at 

; Explain 



;ENT arg block to aat fila eraation tiaa 
;Pointar to 1AD60 fila naaa 
;Vill contain nav eraation tiaa 
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ODTSPC 


.BLKV 


15. 


INSPC : 


.BLXW 


24. 


DKFLI : 


.WORD 


0.0,0,0 


SFTRRt 


.VO&D 


INTJSB 




.WO&O 


NOFILE 




.voao 


BADDEV 


iUFFEl 


.BLIB 


81. 


GETKAN 


.ASCII 


/Sat cr 


GETTIN 


.ASCII 


/N« er 


BADTIN 


.ASCIZ 


/TSFTIM 


INUSE: 


.ASCIZ 


/TSFTIM 


NOFILE 


.ASCIZ 


/TSFTIM 


BADDEV 


.ASCIZ 


/TSFTIM 




.END 


STA&T 



.CSISPC output files 

.CSISPC input filai (flrit !■ tht ona) 

Dafault fil* •xttniloni 

SFTIN arror Hasaaga tabla 



; .GTLIN input buffer 
aation tiaa in fila: /<200> 
aation tlma: /<200> 
-F-InTElld tlaa./ 
-F-Channal in uaa./ 
-F-Can't find fila./ 
-F-Non-diractory davlca./ 



holda tiaa hh:MB:s8 



4.30 Determining or changing the user name 

When, using the LOGON system access program, each user is assigned both a user name and a project- 
programmer number. TSX-Plus provides an EMT which allows an application program to obtain the user 
name or (with SETNAME privilege) to change it. User names may be up to twelve characters in length. If 
the LOGON program is not used, the user name will initially be blank, although it may be changed to a 
non-blank name. The form of the EMT is: 



EMT 



37B 



with RO pointing to the following argument block to determine the user name: 

.BYTE 0.147 
.WORD buff-addr 

where buff-addr is a pointer to a 12-byte area to contain the user name which is returned. 
To change the current user name, RO should instead point to the following argument block: 



BYTE 
WORD 



1,147 
buff-addr 



where buff-addr is a pointer to a 12-byte area containing the new user name. SETNAME privilege is required 
to change the user name. If changing the user name is attempted without SETNAME privilege, the name 
will not be changed and the carry bit will be set on return. 

Example 





.TITLE 


GSONAN 




.ENABL 


LC 


: DaHoinatrata TSX— Plua EMT to 


RRERYT 


=> 62 






.NCALL 


.PiINT..EXIT 


START : 


.P&INT 


iNANEIS 




NOV 


iGSUNAN,10 




EMT 


S7B 




.PilNT 


fNANBUF 




NOV 


fNE¥NAN,NAMADD 




INCB 


GSUNAM 




NOV 


iGSnNAM,KO 




ENT 


876 




BCC 


1$ 




.PilNT 


«NOPtIV 


1$: 


.EXIT 





get/sat uaar nama 
;ENT error coda location 

{Preface uaer naae 

;Point to ENT arg block to 

;Gat uaar naae 

:And dlaplay it 

;Point to new uaar name 

;Set low bit to aet nejta 

;Point to ENT arg block to 

;Set new uaer naae 

;ErrorT 

:Nu8t hare SETNAME privilege 
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.NLIST 


BEX 


GSUNAN 


.BYTE 


0,147 


NANADD 


.VOID 


NANBUF 


NANBDF 


.BLEW 


6 




.VOID 





NEVNAM 


.ASCII 


/CHAOHCT 


NAMEI8 


.ASCII 


/Your eu 


NOP&IY 


. .ASCIZ 


/8ETNAKE 




.ENS 


STAET 



:EKT arg block to gat niar naaa 
;Polnter to racoiTa araa 
:81x vord nana araa (12 bytaa) 
:Naka It ASCIZ 
/ ;Tha nav naaa (12 bytaa) 
t uaar naaa la: /<200> 
/8ETNAKE prlTllaga nacasaarj to aat uaar na«a./ 



4.31 EMT to determine or change program name 

The following EMT allow you to determine or change the name of the current program. This changes the 
name in the SYSTAT (WHO, SHOW JOBS) display, not the directory name of the executable program 
image. The form of the EMT is: 



EMT 376 

with RO pointing to the following argument block: 

.BYTE sub-function, 147 
.WORD buff-addr 

K sub-function is 2 the EMT returns the current program name in RADIX-50 format in the two word buffer 
pointed to by buff-addr. If tub-function is 5 the EMT changes the program name to the RADIX-50 format 
name pointed to by buff-addr. 
The following error code can be returned by this EMT: 



Error 
Code 



Meaning 



The name was not specified in RADIX-50 format. 



Example 



.TITLE SETNAN 

.NCALL .P1INT..BXIT 

.GLOBL P&TDEC.IADASC 

.DSABL OBL 



EULfiYT - 62 



8TA1T : 



NOV 


iGSPNAN.KO 


ENT 


976 


BOS 


It 


NOV 


M.-(SP) 


NOV 


#NANBUF,t6 


NOV 


f2,14 


CALL 


BADA8C 


NOV 


(SP)«,1LS 


.PlINT 


IS 


NOV 


lADNAN. NANBUF 


NOV 


EADNAN«2,NANB 


INCB 


QSPNAN 


NOV 


*GSPNAN,10 


ENT 


876 


BCC 


21 



:ENT arror byta addraaa 

:Polnt to ENT arg. to 

;Gat program nana 

;Branch if not OE 

:SaTa itart addr. of nana 

;Gat addr of itrlng to convart 

;8a7 conTart 2 wordi 

;Gat atart addr. of naaa 
sDiaplay program nama 
; Point to nav program nama 
2 

:Set low byta to aat nama 
iPoint to ENT arg. block to 
;Sat program nama 
{Branch if 01 
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1$: 


MOVB 


t#F.aRBYT.-(SP) 


:Fetch ENT error cod« 




.PEINT 


«EiRIS 


:"EMT trror !•:" 




NOV 


(SP)+,iO 


;E«trl«Tt error cod* 




CALL 


PETDEC 


:DlBpla7 It 


3$: 


DECS 


GSPNAN 


:S«t low byte to get nase 




NOV 


fGSPNAM.EO 


;Polnt to ENT arg. to 




EMT 


S76 


;Get progrtM nuee 




BC8 


11 


;Branch If not OK 




NOV 


E3,-(SP) 


;Puih ES 




NOV 


iNANBOF.EE 


;Get addr of etring to conTert 




NOV 


«3,E4 


;8ej conTert 2 worde 




CALL 


EADASC 






NOV 


(SP)-^.ES 


;Pop ES 




.PIINT 


E3 


;DiBpla7 program naae 




.EXIT 








.NLIST 


BEX 




6SPNAN: 


.BYTE 


2,14T 


;ENT erg. block to get or 




.WOiD 


NANBUF 


;Set program name 


NAMBUF: 


.BLEW 


6 


:Two word name area 


lADNAN: 


.lADEO 


/NEVNAN/ 




Rl&IS : 


.ASCII 
.EVEN 


/TSETNAN-F-ENT 


error ie: /<200> 




.END 


START 





4.32 Setting job priority 

Jobs may be assigned priority values in the range to 127 to control their execution scheduling relative to 
other jobs. The priority values are arranged in three groups: the fixed-low-priority group consists of priority 
values from up to the value specified by the PRILOW sysgen parameter; the fixed-high-priority group 
ranges from the value specified for the PRIHI sysgen parameter up to 127; the middle priority group ranges 
from (PRILOW+1) to (PRIHI-1). The following diagram illustrates the priority groups: 



127 

PRIHI 

PRIDEF 

PRILOW 





Fixed High Priorities 



Normal Job Priorities 



Fixed Low Priorities 



Job scheduling is performed differently for jobs in the fixed-high-priority and fixed-low-priority groups than 
for jobs with normal interactive priorities. Jobs with priorities in the fixed-low-priority group (0 to PRILOW) 
and the fixed-high-priority group (PRIHI to 127) execute at fixed priority values. That is, the priority 
absolutely controls the scheduling of the job for execution relative to other jobs. A job with a fixed priority 
is allowed to execute as long as it wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The fixed-low-priority group is 
intended for use by very low priority background tasks. Normal time-sharing jobs should not be assigned 
priorities in either of the fixed priority groups. 

The middle group of priorities from (PRILOW+l) to (PRIHI-l) are intended to be used by normal, inter- 
active, time-sharing jobs. Jobs with these assigned priorities are scheduled in a more sophisticated manner 
than the fixed-priority jobs. In addition to the assigned priority, external events such as terminal input com- 
pletion, I/O completion, and timer quantum expiration play a role in determining the effective scheduling 
priority. 

When a job with a normal priority switches to a subprocess, the priority of the disconnected job is reduced 
by the amount specified by the PRIVIR sysgen parameter. This causes jobs that are not connected to 
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terminals to execute at a lower priority than jobs that are. This priority reduction does not apply to jobs 
with priorities in the fixed-high-priority group or the fixed-low-priority group. The priority reduction is also 
constrained so that the priority of jobs in the normal job priority range will never be reduced below the 
value of (PRILOW+1). 

The following EMT can be used to set the job priority from within a program. The job priority can also be set 
from the keyboard with the SET PRIORITY command. The current job priority, maximum allowed priority, 
and fixed-high-priority and fixed-low-priority boundaries may be determined with the .GVAL request. See 
the TSX-Plu» Syetcm Manager's Guide for more information on the significance of priority in job scheduling. 
The form of this EMT is: 

EMT 375 

with RO pointing to the following EMT argument block: 

.BYTE 0.150 
.WORD value 

where value is the priority value for the job. The valid range of priorities is to 127 (decimal). The maximum 
job priority may be restricted by the system manager. If a job attempts to set its priority to zero or less, 
its priority will be set to the default value. If a job attempts to set its priority above its maximum allowed 
priority, its priority will be set to the maximum allowed. This EMT does not return any errors. 

Example 



CU&PII 
NAXP&I 
STAIT: 



It: 



.TITLE 
.ENABL 
Damonstrat* 
.MCALL 
.6L0BL 
- -16. 
» -18. 
.PUNT 
.6TAL 
NOV 
CALL 
.PlIKT 
.aVAL 
NOV 
CALL 
ADD 
CNF 
BLE 
NOV 
NOV 
NOV 
ENT 
.PIIKT 
.6VAL 
CALL 
.EXIT 



GSP&I 
LC 
ENT to t«t Job 

.6VAL,.6TLIN,. 
PITDBC 



AlEA: 
SETPtI : 
NEWPII: 



CVIIS 
NAXIS 
NEVIS 



priority 
PUNT,. EXIT 



.BLEW 

.BYTE 

.VOID 

.NLI8T 

.ASCII 

.ASCII 

.ASCII 

.END 



iCU&IS 

iAEEA.iCUEPEI 

10,11 

PITDEC 

iNAXIS 

iA&EA.iMAXPil 

10,12 

PITDEC 

#10., 11 

11.13 

II 

12,11 

ll.NEVPlI 

iSETPlI.lO 

S75 

ffNEVIS 

iAlEA.tCDlPlI 

PITDEC 



GVAL offiat to got currtnt priority 
GVAL offaot to gat bbxIbub priority 
"currant priority li" 
Obtftin currant Job priority in 10 
Sara it 

and dliplay it 
"■axlBUH priority la** 
Obtain MJclMua allovabla Job priority 
SaTO it 

and dlaplay It 
Try to booat priority by 10 
Unlaaa axcaada maxlauH 
Uaa 10 largar if <- mai^ri 
Elaa uaa aaa^ri 

Sat naw priority In ENT arg block 
Point to ENT arg block to 
Saat naw Job priority 
"naw priority la" 
Obtain naw priority 

and dlaplay it 



10 

0.160 

60. 

BEX 

/Currant Job priority ■ /<200> 

<16><12>/NaxlBua Job priority 

<16><12>/- Maw - Job priority 

STAIT 



;Ganaral ENT arg block 

;ENT arg block to aat Job priority 

;Naw Job priority goaa haro 



/<200> 
/<200> 
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4.33 Determining or changing job privileges 

A TSX-Plus EMT is available to allow running programs to determine the privileges for the job and to 
change privileges. This is particularly useful to check user-defined privileges. See the TSX-Plue System 
Manager's Guide for complete information on job privileges. The form of the EMT argument block is: 



ENT 



375 



with RO pointing to an argument block of the following form: 



.BYTE 


1.150 


.BYTE 


fuBCtion.privtype 


.WORD 


buffer 


.WORD 






where buffer is the address of a four word buffer which contains the privilege flags to be set or cleared or 
which will receive the privilege flags. Note, not all of the privilege words may be in current use, but four 
words should be reserved to allow for future expansion. Function indicates the type of operation being done 
and must be 0, 1, or 2 according to the following table: 




Meaning 



Read job's privilege flags into buffer 

Clear bits set in buffer in job's privilege flag bits 

Set bits set in buffer in job's privilege flag bits 



Functions 1 and 2 are bit-clear and bit-set operations so that individual privileges may be selectively changed 
without afl'ecting other privileges. 

Privtype indicates which of the three sets of privilege flags are to be accessed, and must be 0, 1, or 2 according 
to the following table: 



Privtype 


Privilege table 



1 
2 


Current privileges 
Set privileges 
Authorized privileges 



The current privileges for the job are reset to the set privileges when the currently executing program exits. 
If set privileges are changed, then current privileges are changed as well. If authorized privileges are changed, 
then net and current privileges are changed as well. SETPRV privilege is required to set any new privileges 
in the authorized privilege set. 



Error 
Code 



Meaning 



Attempt to enable privileges for which the job is not authorized. 
Only those privileges for which the job is authorized are set. 



Example 



•TITLE SETPiV 
.ENABL LC 
.DSABL GBL 
Draonitrat* ENT to datarmln* or itt prlTllogai 
.MCALL .PiINT,.EXIT..TTYOUT 
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.CLOBL PITOCT 




SPACE 


* 40 : 


ASCII SPACE 


SEiBTT 


« S2 1 


ENT EEEOE BYTE 


STAIT: 


CALL SHOPIV : 
.PlIKT iClLF 


DISPLAY PEIVILEGES BEFOEE 




NOTE ta.ics 


WANT TO SET PEIV FLAGS 




MOVE tl.CSA 


SELECT "SET" PEIVILEGES 




NOV tTOO.PEIVS 


SET 3 PEIV FLAGS IN PEIV WOED 1 




CLE PEIVS+2 


DO HOT CHANGE ANY IN PEIV WOED 2 




N0¥ •GSPEIV.IO 


.POINT TO ENT AEG BLOCI TO 




EHT 376 


:SET SOHB PRIVILEGE FLAGS 




BCC 1$ 


:BEANCH ON EEEOE 




MOVE tiEiaBYT,-(SP) 


;ELSE GET EEEOE BYTE 




ADD i'0.(8P) 


;CONVERT TO DIGIT 




.PEIKT ffE&E 






.ITTOUT (SP)* 






.PEINT #CRLF 




11: 


CALL SHOPEV 
.EXIT 


; DISPLAY PEIVILEGES AFTEE 


8H0P1V : 


.PEINT #AUTPEV 


!"AOTH0EIZED" 




MOVE #2, CSA 


:L00I AT ACTHOEIZED PEIVILEGES 




CALL DSPPEV 


;E£AD AND DISPLAY FIE8T 2 PEIV WI 




.PEINT iSETPEV 


;"SET" 




MOVE tl.CSA 


:LOOX AT SET PEIVILEGES 




CALL DSPPEV 






.PEINT #CDEPEV 


:"CDRRRNT" 




CLEE CSA 


;LOOI AT COERRNT PEIVILEGES 




CALL DSPPEV 


:DISPLAY PEIVILEGB BITS 




EBTUEN 




DSPPEV 


: CLEE ECS 


;EEAD PEIVILEGES 




MOV tGSPEIV.EO 


•.POINT TO ENT AEG BLOCK TO 




ENT 376 


-.EEAD SELECTED PEIVILEGES 




NOV PEIVS.EO 


;GEI PEIV WOED 1 




CALL PETOCT 


:DISPLAY ITS BITS 




.TTTOUT f SPACE 






MOV PEIVS«2,E0 


-.GET PEIV WOED 2 




CALL PETOCT 






.PEINT iCELF 






EETVEN 




GSPtm 


: .ETTE 1,160 


: GET/SET PEIVILEGE ENT 


ICS: 


.ETTE 


:0>E£AD.1-CLEAE.2-8ET 


CSA: 


.BYTE 


;0-CURRKNT . 1-SEI ,2-ADTHOEIZED 




.YOED PEIVS 


:PUT PEIV FLAGS HERE 




.YOEO 


:EEqUIEED 


PlIVS 


.WOED 0,0,0,0 
.NLIST BEX 


: PEIVILEGE FLAGS 2 OF 4 DEED 


AUTPIV: .ASCII /Authorlied priTlltgei: /<200> 


SETPIV: .ASCII /S«t priTll«gti 


/<200> 


COEPIV: .ASCII /Cnrrtnt privl] 


•gai: /<200> 


CILF: 


.A8CIZ // 




EU: 


.ASCII /Stt priTlltg. 
.LIST BEX 
.END 8TAET 


trror f /<200> 



4.34 Specifing that a file be placed in HOLD or NOHOLD mode 

The following EMT is used to dynamically request that a file being printed through the spooler be either 
held until the file is closed or begin printing as data is made available from the program. This could be used 
in a situation where NOHOLD is the normal condition, but a program which uses the printer generates data 
slowly. If data were paased to the printer as soon as available, then printer output from all other jobs would 
be delayed until the slow job closes the output. This can be avoided by the having the slow program select 
hold mode for its output. Then, other jobs can proceed to use the printer without being delayed by the slow 
job. The form of the EMT to select HOLD or NOHOLD mode on an individual file basis is: 



EMT 



375 



4.S4. SPECIFING THAT A FILE BE PLACED IN HOLD OR NOHOLD MODE 
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with RO pointing to the following argument block: 

.BYTE Chan, 151 
.WORD 
.WORD flag 

where chan is the channel number which has been used to open the print file and flag indicates whether 
the file is to be printed as it is generated or held until the file is closed. If flag=0, the output is printed as 
generated (equivalent to NOHOLD); i£ flag=l, then the output is not printed until the file is closed. This 
EMT must be issued after a channel has been opened to the printer (through the spooler), but before any 
data has been written to it. If the channel is open to any non-spooled device, then the EMT is ignored. 

Example 



.TITLE SPHOLD 
.ENABL LC 
Demonstrate tht ENT to hold spooler output until the file ii closed 
.NCALL .CSISPC, .LOOKUP, .&EADV, .WIITV. .CLOSE. .EXIT 

ENT error code byte location 



EULBTI 
STAiT : 



OPNFIL 



6IVEDT; 



» 62 

.CSISPC 

BCS 

NOV 

.LOOKUP 

BCS 

NOV 

NOV 

ADD 

NOV 

NOV 

TST 

.LOOKUP 

BCC 

.CLOSE 

.EXIT 



fOUTSPC,«DEFEXT,*0 

START 

fINSPCll 

tA&EA,*0,&l 

STAET 

ffOUTSPC,R2 

#*iLP ,(12)+ 

i2,&l 

(I1)*.(R2)+ 

(R1)-^.(R2) + 

(Rl) + 

•Aa£A,fl,»OUTSPC 

NOHOLD 

«0 



Tell spooler to hold file until It la closed 
(■uit be Issued before any writes to file) 



Get naae of file to copy 
Proceed unless error 
Point to first input filspe 
Try to open input file 
Get a new eoamand on error 
Point to output filspe 
Put LP: in output filspe 
Point to input filspe filename 
NoTe file naae into LP filspe 

(not necessary, but eonrenient) 
Skip over file extension 
Open channel to printer (spooled) 
Proceed unless error 
Close input file 
And glTe up 



NOHOLD: 



61: 



8$: 



NXTFIL: 



AREA: 
SPHOLD : 

HNH: 
0UT8PC: 
INSPC: 
DEFEIT : 
BUFFER: 



NOV 

ENT 

CLR 

.EEADW 

BCS 

.WRITir 

BCC 

.CLOSE 

BR 

INC 

BR 

.CLOSE 

.CLOSE 

TST 

BNE 

BR 

.BLKW 

.BYTE 

.¥ORD 

.VORD 

.BLKW 

.BLKW 

.WORD 

.BLKW 

.END 



iSPHOLD.RO {Point to ENT arg block to 

S7E ;Hold output until close 

K2 : Initialise block pointer 

«AREA,fO,«BUFFER,«266.,R2 :Copy a block from the file 
NXTFIL ;Try next file on error 

iAREA.*l,»BUFFER,i2E6..R2 :Copy the file block to LP 



8$ 
«1 

GIVEUP 
R2 

ei 

«o 

ii 

2(R1) 

OPNFIL 

START 

10 

1.161 



1 

IE. 

24. 

0.0,0,0 

266. 

START 



:ErrorT 

:Close print file 

; Forget it 

;Polnt to next block 

;And get next block 

; Close input file 

:and print file 

:Any input flleT 

:Repeat if no 

;Else ask for more files 

; General ENT arg block area 

:ENT arg block to hold spool output 

;on channel 1 until file is closed 

:HNH<^0 Ined; HNH^l hold til close 

; Output file apeca 

; Input file specs 

:No default file types 

;I/0 buffer area 
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4.35 Program controlled terminal options 

Programs may dynamically change various parameters related to terminal control. The following EMT may 
be used to set various program controlled terminal options: 

EMT 37E 

with RO pointing to the following argument block: 

.BYTE 0.152 

.¥ORD function-cod* 

.WORD argtunent-value 

where function-code is a character which specifies which option is to be set or changed, and argument-value 
specifies a value used only by some options. See Chapter S on program controlled terminal options earlier in 
this manual for more information on the specific options which may be selected and details on their effects. 

Example 

See the example program EMTMTH in Chapter 3. 

4.36 Forcing [non] interactive job characteristics 

The following EMT can be used to cause a job to be scheduled either as an interactive job or as a non- 
interactive job. Programs which do a large amount of terminal input, but which are not truly interactive jobs 
in the usual sense, such as file transfer programs, should use this EMT to avoid excessive interference with nor- 
mal interactive time-sharing jobs. This feature may also be selected with the R [UN] /NONE^TER ACTIVE 
command. See the TSX-Plut System Manager 't Guide for more information on job scheduling and the 
significance of interactive vs. non-interactive jobs. The form of this EMT is: 

EKT 375 

with RO pointing to the following argument block: 

.BYTE 0.153 
. WORD mode 
.WORD 

If the value of mode is 0, then the job will never be scheduled as an interactive job. If mode is 1, then the 
job will be scheduled as other interactive jobs are, dependent on terminal input. 

Example 



.TITLE NONIHT 

.ENiBL LC 
Otmonitrtt* ENT to tchvdulw job u intoractlTo or non-lotoraetiTO 

•KCALL .TTYIH,.TTY0BI,.P1INT,.EXIT 

;Jeb St&tui Vord addrttt 

;TT ■pocial modo bit (ilnglo-ehar) 

: ASCII CT&L-Z (boto ob eoMBand) 

; Point to ENT mrg block to 

:Turn on olnglo character actlTatlon 

; Finish turning on alnglo char aodo 

:Polnt to EHT arg block to 



JSV 


- 44 




TTSPC 


- 10000 




CTiLZ 


' 32 




STAKT: 


NOV 


«SINGLE.10 




ENT 


376 




BIS 


•TTSPC. tfJSW 




NOT 


fNONINT.IO 
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i<: 



21: 



31: 



4(: 

SINGLE: 



NONINT: 
SELECT : 



SLOV: 



FAST: 



ENT 

.PRINT 

.TTYIN 

CNPB 

BEq 

.TTYOUT 

Bl 

NOV 

MOV 

ENT 

.P&INT 

.TTYIN 

CNPB 

BEQ 

.TTYOUT 

B& 

.EXIT 

.BYTE 

.VOED 

.VO&O 

.BYTE 

.VOU) 

.VOU) 

.NLIST 

.ASCII 

.ASCII 

.ASCII 

.ASCIZ 

.ASCIZ 

.END 



376 

fSLOW 

IO,«CT&LZ 
21 



1$ 

#1, SELECT 
«N0NINT,IO 
S7B 
»FAST 

IO,*CT&LZ 
41 

3$ 



Schadule thli ai non-lnttractlT* Job 

"Nay b* ilov nov if eyttam baiy" 

Gat a char 

II CTiL-Z 

Then aova on 

Elsa acho It back (v« hava to acho 

whan in alngla char aoda) 
And rapaat 

Vant to ba IntaractiTa now 
Point to ENT arg block to 
Schadula this at an IntaractiTa Job 
"Sea how Buch faatar now" 
Get a char 
II CTiL-Z 
Then aoTa on 
Elia acho It back 
And repeat 



0,162 

'S 



0.163 





BEX 

/Type SOB* character! In now 

/InteractiTe Jobi/<lB><12> 

/reeponae will be alow. (Control-Z to get out / 

/of thla mode.)/ 

<16><12>/Tr7 again, leaponae should bo much better./ 

START 



;ENT arg block to aet tent option 
; Single char actlratlon 

;ENT arg block to ached aa [nonllnteractlre 
; Initially make non-lnteractlre 



If the ayatem haa aararal / 



4.37 Setting terminal baud rates 

The transmit/receive speed for time- sharing lines or CL lines may be set either with the keyboard command 
SET TT SPEED or from within a program. Use of this EMT requires TERMINAL privilege. Line speeds may 
only be set for terminal interfaces which support programmable baud rates, such as: DLVll-E, DZ(V)11, 
DH(V)11 type interfaces and the PRO-S50 printer, communication and QSL ports. The EMT to set line 
speeds from within a program is: 



EMT 



375 



with RO pointing to an argument block of the form: 



.BYTE 0.154 
.WORD line -number 
.WORD line-parameters 



(OPLxSSSS) 



where line-number indicates the TSX-Plus line number for which the speed is to be set. If line-number is 0, 
then fche speed is set on the line from which the EMT is issued. Line-parameters is a combined word which 
is used to specify the speed, number of data bits, and parity control. Bits 0-3 "SSSS" select the baud rate 
according to the following table: 
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Speed 


Octal Code 


75 


1 


110 


2 


134.5 


8 


150 


4 


800 


5 


600 


6 


1200 


7 


1800 


10 


2000 


11 


2400 


12 


8600 


18 


4800 


14 


7200 


15 


9600 


16 


19200 


17 



Split speeds (different transmit and receive baud rates) are not supported. Bit 4 (i) is not used. Bit 5 (I) 
specifies the character length. If this bit is 0, the character length is 8 bits; if this bit is 1, the character 
length is 7 bits. Bit 6 (P) specifies if parity control is wanted. If this bit is 0, no parity is selected and bit 
7 is ignored; if this bit is 1, parity generation and checking is enabled. Bit 7 {O) selects even or odd parity 
and is only meaningful if bit 6 is 1. If bit 7 is 0, even parity is selected; if bit 7 is 1, odd parity is selected. 
Note that if only the speed value is specified, with all other bits zero, 8 bit characters with no parity are 
selected. 

A baud rate of 19200 is not supported by DEC DZ(V)11 controllers. DHVll interfaces do not support 8600 
or 7200 baud. DHll interfaces do not support 2000, 8600 or 7200 baud. The PRO QSL interface does not 
support 8600 or 7200 baud. 



Error 
Code 



Meaning 



Job does not have TERMINAL privilege 
Invalid line number specified 



Example 





.TITLE 


SETSPD 






.ENABL 


LC 




Dtaonstrat* 


ENT to set a lln* 


'■ tranimlt/rtcclT* baud rat* 




.NCALL 


.PEINT,.EXIT 






.GLOBL 


PETDEC 






.DSABL 


GBL 




RE&RYT 


» 62 




:ENT arror bjta addraas 


STAIT : 


NOV 


iSETSPD.EO 


:Point to ENT arg block to 




ENT 


S7B 


:Sat Una apaad 




BCC 


91 


'.Branch if OX 




NOTB 


•fEEEBYT.-(8P) 


: Patch ENT arror coda 




.PlIKT 


iEUIS 


;"ENT arror la:" 




MOV 


(SP)*.EO 


;EatrlaTa arror coda 




CALL 


PETDEC 


:Di8pla7 it 


9(: 


.EXIT 






SETSPD : 


.BYTE 


0.164 


:ENT arg block to aat Una apaad 




.VOID 


6 


;Llna nuabar 




.WOiD 


14. 


;Spaad coda for 9600 band 




.HLI8T 


BEX 




RR&IE : 


.ASCII 


/TSETSPD-P-ENT trror eodt - /<200> 




.EVEN 








.END 


8TAET 





4.38. RAISING AND LOWERING THE DTR SIGNAL ON A LINE 63 

4.38 Raising and lowering the DTR signal on a line 

The following EMT can be used to raise or lower the DTR (data terminal ready — pin 20 on and EIA/RS232- 
C connector) signal on a line. This is only effective if the interface supports modem control signals (e.g., 
this has no effect on a DLVllJ port). This can be useful in situations where a modem or data PBX requires 
the DTR signal. 

The DTR signal is also manipulated by the system when connecting and disconnecting "phone" lines. 
The form of the EMT is: 

EMT 375 

with RO pointing to the following EMT argument block: 

.BYTE sub-function, 154 
.BYTE 1 ine -number, 
.WORD speed 

where line-number indicates which physical line is to be affected, speed is only used with subfunction (zero), 
and sub-function controls the subfunction to be performed, as follows: 



Error 
Code 



Meaning 



Set line speed (see previous description for 0,154) 
Reset line XOFF status 
Raise line DTR 
Lower line DTR 



TERMINAL privilege is required to issue this EMT unless the line to be affected is the job issuing the EMT. 
Example 



.TITLE SETDT& 

.HCALL .PIINT,.KIIT..GTLIN 

.DSABL GBL 

.GLOBL AC&DEC.P&TDEC 



STAil 


': MOV 


«BUFFEi,ll 






.PRINT 


ilNST&C 


;Prlnt liiBtruetloni 




.GTLIN 


Il.iVHICH 


:Aak for lln* niubtr 




CALL 


ACRDEC 


iConrert It froa ascii nuBbar 




TST 


10 


:Sat or cloarT 




BGT 


11 


:Bruieh if tot 




NEG 


RO 


SPoiltlTO 




NOV 


lO.CLRLIN 


:8aT« lino niubor 




MOV 


fCLRDTR.RO 


:Polnt to ENT arg block to cloar DTR 




BE 


21 


:Bruich to ENT 


11: 


NOV 


RO.SETLIN 


;SaTO lino nuMbor 




NOV 


•SETDTR.RO 


iPolnt to ENT arg block to ralao DTR 


21: 


EMT 


37E 


:Do ENT 




BCC 


0$ 


;Braneh If no orror 




NOVB 


•«E2,-(SP) 


;Elit got orror codo 




.PRINT 


tEMTRSR 


;"SET DTR error nuaber:" 




NOV 


(8P)*.R0 


;RetrloTO orror codo 




CALL 


PRTDEC 


:And display It 


H: 


.EXIT 








.NLIST 


BEX 
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CLIDTI: 

CLILIN: 

SETDTl: 

SETLIM: 

BUFFEl: 

INSTIC: 

VHICH: 

EMTEU: 



• BYTE 

.fO&D 

.BYTE 

.WOIO 

.BLIB 

.ASCIZ 

.ASCII 

.ASCII 

.EVEN 

.ENS 



S.1B4 ;EMT «rg. block to lowor DTi 

0.0 

2,154 ;ENT arg. block to raiio DTI 

0,0 

81. 

/To ralao DTI ontor th« lino numbor;/ 

/to lowor ontor tho nogatlTO lint numbor: /<200> 

/SET DTI orroE # /<200> 

STA&T 



4.39 Assigning a CL unit to a time-sharing line 

Time-sharing terminal lines which are not in use may be reassigned as general purpose serial I/O lines by 
directing the TSX-Plus CL facility to assign a CL unit to the line. This can be done either with a keyboard 
command (see the SET CL LINE=n command in the TSX-Plu» User's Rcfercnct Manual) or from within 
a program. A special system service call (EMT) is available to assign a CL line from within a program. Use 
of this EMT requires TERMINAL privilege. The form of the EMT is: 

EMT 375 

with RO pointing to an argument block of the form: 

.BYTE 0.155 
.WORD cl-unit 
.WORD line-nximber 

where cl-unit specifies the CL unit number to be assigned to the line, and line-number identifies the TSX- 
Plus line number to be disabled as a time-sharing line and reassigned as a CL unit. The valid range of CL 
unit numbers is determined by the number of CL units defined during TSX-Plus system generation. For 
example, if 5 CL units are defined, then the valid CL units are CLO, CLl and CL2. K line-numher is zero, 
then the CL unit is disassociated from the line and the line is restored to its previous function. The line 
number may also refer to lines generated as dedicated CL lines. In this case, when a CL unit is disassociated 
from the line, it is simply returned to a pool of lines available for CL use. It does not become redefined as 
a time-sharing line. 
See Chapter 7 and the TSX-Plut System Manager's Guide for more information on CL units. 



Error 
Code 



Meaning 



"Job issuing request does not have TERMINAL privilege 
Invalid CL unit number specified 
Invalid line number specified 

Specified line number already assigned to a CL unit 
Specified line number in use for time-sharing 
Specified CL unit is currently busy 



Example 



.TITLE GETCL 
.ENABL LC 
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Demonitratt EMT to iwltch tlat-iharing lln« to CL lino 

Dowonitratt ENT to allocate a dovlco 

Damonitrato .SPFUN roquoat to CL 

Thia oxaapla attoapta to attach a CL unit to 

It lino which la llnkad to anothor aachlno, 

mllocatt it for axclaalTo uao, 

modify tho default CL aottlnga, 

imd than otart up tho IT— 11 VTCOM utility. 
Sinct it la difficult to aaXo logical aaaignaontii from within 

11 progras, uao a apecial .EXIT to paaa tho ASSIGN conand to 

KMON and then run VTCOM, 

.MCALL .PEINT,.EXIT,.L00IUP,.8PFirN..PUIGE 
.DSABL GBL 

;ENT error byte addreaa 

;Job Statua Word addreaa 

: Chain Infonutlon hit in JSV 



62 
44 

4000 



EUBY!ir 

JSW 

CKNIFII 

8TAIT : 

; laiiue EMT to attach the line 

NOV fATTCL.KO 

EMT S7E 

BCC 11 

: ENir error, 

NOVB 

ASL 

.PRINT 



:Point to ENT arg block to 
; Attach CL unit to T/S line 
:Branch if 01. elae 
explain it before exiting 

•«E&&BYT,11 ;6et ENT error code 

Kl :ConTert error byte to word index 

ATTEU(ll) ;Print appropriate error BeaBage 



1$ 



BR 101 :And force alMple exit 

Allocate device ao nobody elae infrlngea It 



NOV 
EMT 
BCC 
ENi; error, 
NOVB 
ASL 
.PRINT 
BR 



tALOCAT,RO ;Point to ENT arg block to 

S75 : Allocate CL for exelualTo uao 

21 :Branch if 01, alee 
explain it before exiting 

•«ERRBn,Rl ;Get ENT error code 

*1 ; Convert to word Index 

ALLERR(Rl) ;Prlnt appropriate nrror meaaage 

10$ ;And exit 



; laiiue SET CL conand (not the eaaieat way to do thia). 
; If a channel were already open to CL, then thia would 
i Ba):e more aenae. But, aa an example, why not? 
3$: .LOOIUP iAREA,fO,fCLUNAN ;Open a channel to CL 

.SPFUN #AREA.#0.#2Bl,fCLFLAG.i0.iO ;Tum off flagged optiona 

.PURGE #0 ;Done with channel 

: Set up for apecial exit paaaing coamanda to INON 



3$: 



101 



AREA 

CLFLAG 

ATTCL: 



ALOCAT 



CLUNAN: 



NOV #C0NAND.R1 ;Point to command line text 

NOV #B10,R2 ;Point to chain info area 

NOV #C0NLEN,(R2)* ;» of bytea In chain data area 

NOVB (R1)*,(R2)* :NoTe eommajid linea Into chain area 

CMP Il,»CONEm) :Reached end yetT 

BLO 31 :Repeat if not 

BIS #CHNIF$,f»JSW ;Set paaa command bit in JSW 

;(abortB any pending command file) 
; Required for apecial exit 
;Re8et atack pointer 
;Done (Note: unit remaina allocated 
i after program exit!) 

ENT arg blocka and word buff era 



CLR 
NOV 
.EXIT 



RO 
»1000,SP 



.BLIW 

.WORD 

.BYTE 

.WORD 

.WORD 

.BYTE 

.WORD 

.RADEO 

.WORD 



10 
10 

0,166 


e 

0,166 
CLUNAN 
/CLO/ 
0,0,0 



; General purpoae ENT arg block 

;NOLFOUT flag for CL .SPFUN 

;ENT arg block to take over T8 line by CL 

; Selected CL unit number 

; Selected TS line number 

:ENT arg block to allocate a device 

; Addreaa of 4-word device apeclfication 

: Start with firat CL unit 

; Dummy file apeclfication 



Genoral meaaagea and byte buffera 
.NLIST BEX 
CONAND: .ASCIZ /ASSIGN CLO XL/ jNake logical aaalgnaent of XL for VTCON 
•ASCIZ /R VTCON/ ;lun VTCON (part of llTll V5.01 kit) 
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CONLEN 



ATTE&l: 



NOPIIV 
BADCLU 
BADTSL 
ALIDCL 
INDISE: 
CLBUST 



iLLEU: 



ALIOAL 
BADDEV 
ALLFUL 
DEYUSE 



.LIST 

.EVEN 

c COMEND 

.If 

.EUOI 

.EHDC 

.WOEO 

.WOU 

.VOID 

.VOID 

.VOID 

.VOU) 

.VO&O 

.NLIST 

.A8CIZ 

.A8CIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.LIST 

.EVEN 

.VOID 

.WOU) 

.WOiD 

.WOU> 

.VOEO 

.NLIST 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.LIST 

.EVEN 

.END 



BEX 

-COMAND ;• bytei In conutdi passtd to IMON 

CI <COMLEN-<1000-B12» 

1 : Chain data arta OTtrllow 



; Attach CL ENT trror aaaaag* tabic 

: 1 

: a 

: 3 

: 4 

: B 

: 6 





NOPIIV 

BADCLU 

BADTSL 

ALiDCL 

INUSE 

CLBDSY 

BEX 

/Not prlTllogttd to oat thli prograa./ 

/Attrapt to usa inralid CL unit./ 

/AtttBpt to uso InTalid tlaa-aharlng Una./ 

/Tlaa-aharlng lint alraady in oat aa CL unit./ 

/SoBobod7 io alraady naing tiBt-aharing lint./ 

/CL unit alraadj aetiya./ 

BEX 



:Allocato ENT arror tablo 
: 1 
: 2 
; S 
: 4 





ALRDAL 

BADDEV 

ALLFUL 

DEVUSE 

BEX 

/CL unit already allocattd by aoaaona alaa,/ 

/Cannot allocata that darlea./ 

/Too many dtvlcta alraady allocattd./ 

/DtTlea in oat by aoaaont tlat./ 

BEX 

START 



4.40 Allocating a device for exclusive use 

Devices may be allocated for exclusive use by a single user. This prevents mixing input and output on 
common, but non-spooled, devices like a communications line (XL or CL devices) or a magnetic tape. 
Access restriction by device allocation remains in effect until deallocated by the job or until the job logs 
off. See the description of the ALLOCATE command in the TSX-Plua U$cr'8 Reference Manual for more 
information on device allocation. 

There are three system service calls relating to device allocation: allocate a device; deallocate a device; check 
to see if a device is allocated by another user. Use of these EMTs requires ALLOCATE privilege. The form 
of the EMT is the same for all three: 

EMT 375 

with RO pointing to an argument block of the form: 

.BYTE n,lB6 

.WORD devic«-pointer 

where device-pointer is the address of a four-word block in which the first word contains the RAD50 name 
of the device to be allocated and the next three words contain zeros. The specific function is defined by the 
first byte of the argument block, as follows: 



Function 



Allocate a device 

Deallocate a device 

Check to see if a device is allocated by another user 
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You can only allocate a device if no other user has abeady allocated the device or hna a channel open to it. 
If the device is allocated to another job or another job has a channel open to the device, then the number 
of the job which is accessing the device is returned in RO. If a job which has already allocated the device 
or has a channel open to the device is not associated with the same primary line as the job attempting to 
allocate the device, then the carry bit will be set on return from the EMT and the number of the job which 
is accessing the device will be returned in RO. If the device is currently allocated by a job which was started 
from the same primary line as the job which is now attempting to allocate it, then the carry flag will be 
clear on return, but the other job number will be returned in RO. If both the job with the current allocation 
and the job attempting to allocate the device are subprocesses, the first one to allocate the device gets the 
allocation. If either is the primary line, then the primary line will get the allocation. 



Error 
Code 



Meariing 



Device is already allocated by another job 
Invalid device specified 

Device allocation table is full (TSGEN parameter MAXALC) 
Device is currently in use by another job 

Job does not have ALLOCATE privilege (subfunction to check de- 
vice allocation does not require privilege) 



Example 

See the example program GETCL in section 4.39 on assigning a CL unit to a time-sharing line. 

4.41 Job monitoring 

A monitoring watch may be established to allow a job to monitor the status of other time-sharing jobs. For 
example, if a detached job were being used as a common file server for several other jobs, it would be useful 
to know if a served program with a pending request aborts. The outstanding request could then be purged. 
The monitoring facility may also be used in lieu of message channels (see Chapter 6) when only a small 
amount of information needs to be communicated (e.g., one word). 

When a job is being monitored, the operating system will report certain job status changes, such as logging 
on, starting or exiting a program, or logging oflT. In addition, the monitored job itself may issue status 
reports to any job which may be monitoring it. After a job has established a monitor watch for a given 
line, a completion routine is entered in the monitoring job whenever a monitor status report is bsued for the 
monitored line, whether the report was bsued by the monitored job itself or by the system because of a status 
change. Job monitoring may be used effectively in conjunction with inter-job message communications and 
with detached jobs. 

There are three system service calls related to job monitoring. All have the form: 



£NT 



375 



with RO pointing to an argument block of the form: 

.BYTE n.lB7 

. WORD j ob-number 

.WORD completion-routine 

where n designates which job monitoring function is to be performed, j'ob-rtumbcr designates the line number 
which is to be monitored, and eomplction-routmt is the address of a completion routine in the monitoring 
job which is to be entered whenever a monitor status report is generated for the line being monitored 
{job-number). The job-number may designate any primary time-sharing line, detached job or subprocess 
job number. It may not refer to a dedicated CL line. Job-numbers (lines) are assigned in the following 
order: time-sharing lines in the order they were declared during system generation, starting with number 
1; detached job lines; subprocess lines. Detached jobs and subprocesses are assigned to line numbers in the 
order they were activated. Unused detached lines are reserved and are never assigned to subprocesses. 
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4.41.1 Establishing a monitoring connection 

The form of the argument block to establish a monitoring connection with a line is: 

.BYTE 0,157 

.WORD job-ntuttber 

.WORD completion-routine 

U job- number is zero, then all jobs are monitored, including those not currently logged on. 



Error 
Code 



Meariing 



Invalid job number specified 

No free job monitoring control blocks (increase TSGEN parameter 

MAXMON) 



The specified completion routine will be entered whenever a monitor status report is issued for the specified 
job-number. On entry to the completion routine, the low order byte of RO contains the line number of the 
job originating the monitor status report. Note that the same completion routine may be specified when 
monitoring more than one job. The high order bit (mask 100000) of RO will be clear (0) if the monitor status 
was originated by the system and will be set if the monitored job itself issued the status. Rl will contain a 
16-bit status value. Status values generated by the system for monitored lines are: 



Status Code 


Meaning 


1 
2 
3 
4 
5 


Job has been initialized 

Job has logged on using the LOGON program 

Job has started running a program 

Job has retiirned control to the keyboard monitor 

Job has logged off 



Status code 1 is generated when a logged off line is started, usually by typing a carriage-return at that 
terminal. Status code S is generated whenever a program is either run or chained to. Status code 4 is 
generated whenever a program exits or is aborted, but not when it chains to another program. 



4.41.2 Cancel a monitoring connection 

The form of the argument block to cancel a monitoring connection with a line is: 

.BYTE 1,157 
.WORD job -number 

If job-number is zero (0), then all job monitoring connections established by the monitoring job (the job 
issuing this EMT) are cancelled. All job monitoring requests are also cancelled if the job exits, aborts, chains 
or issues a .SRESET or .HRESET. 



Error 
Code 



Meaning 



Invalid job number specified 
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4.41.3 Broadcast status report to monitoring jobs 

The form of the argument block to broadcast a monitor status report is: 

.BYTE 2,157 

.VORD status- value 

where ttatua-value is a 16-bit value to be broadcast to all jobs which are monitoring the job which broadcasts 
the status-value (the job issuing this EMT). On entry to the completion routine in the monitoring job(s), the 
status-value is in Rl, the low byte of RO contains the job-number of the job broadcasting the status-value, 
and the high-order bit of RO (mask 100000) is set (1). 



Error 
Code 







Meaning 



No jobs are monitoring this line 



Example 



.TITLE MONCPL 

.ENABL LC 
Dnionitrats Job aonltorlng completion routine*. 
Watch ai dial-in Una and announca when it la actlTated. 

.MCALL .PRINT,. EXIT.. SPND,.ESOT< 
GBL 



EULBYT 
NONLIir 
NFYLIH 
STAiT : 



.DSABL 
.GLOBL 
* E2 

- 8. 

- 1. 
NOV 
ENT 
BCC 



lEOASC 



«NONJOB,10 

S7B 

II 



;ENT error byte addreaa 
;Llne number to be monitored 
;Lln* number to be notified 
;Point to ENT arg block to 
; Schedule Job monitor compl rtn 
; Branch if OK 



; Job monitoring achedullng error 

NOVB ««E&&BYT,&1 ;Get ENT error code 
ADD #'0,il ;ConTert to ASCII 

NOVB 11.E&&C0D ;Stuff into error aeaaage 
41 : .PRINT fCPLERR ;Eeport error 

.EXIT ;And abort 

; Valt for event on monitored line 
1<: .8PND ;Wait for erent 

BR 4$ ;Only get here on error 

; Coaipletion routine which la entered when erent oecura on monitored line 
NOMCPL: NOV 10, SENDER ; Remember whoae monitor report 
*M0NJ0B,RO ; Point to ENT arg block to 
S7E ;Reachedule myaelf 

II iBranch If 01 

C»ERRBYT,RO :Get error code 
*'0,R0 ;ConTert to ASCII 
RO.ERRCOD ;SaTe error code 

;ReBtart mainline and report error 
; Abort co^tletlon routine 
:Waa thla a ajatem generated meaaageT 
: Ignore If not 
: Running program? 
; Branch if not 
: Point to ENT arg block to 
;Get program name 

; Note that a ahort program may already hare returned to XNON by now! 
NOV «R50BLX,R0 :Polnt to program name 
CALL R60ASC iConvert into ASCII In meaaage 
21: DEC Rl ;0 index atatua code 



II 



NOV 

NOV 

ENT 

BCC 

NOVB 

ADD 

NOVB 

.RSUM 

BE 

T8T 

BNI 

CNP 

BNE 

NOV 

ENT 



SI 

SENDER 
SI 

Rl,*3 
21 

«GPRGNM.RO 
S7E 
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NUL 


iCODLEN.ll 




ADD 


f CODBEG, 11 




NOV 


ll.NSADK 




NOV 


iNOIIFY.EO 




ENT 


375 


SI: 


&ETU1M 




: ENT 1 


trguavnt 


block* and word 


NONJOB: 


.BYTE 


0,1B7 




.¥010 


NONLIN 




.VOID 


NONCPL 


HDIIFT: 


.BYTE 


0,127 




.VOID 


NFYLIN 


NSADl: 


.VOID 





GPIGNM: 


.BITE 


0.144 




.BYTE 


NONLIN, E 




.VOID 


KEONAN 


150BLI: 


.VOID 


I60NAN 




.VOID 


P&GNAN 




.VOID 


6 


IBOHAN: 


.VOU) 


0.0 


SENDEl: 


.VOID 





: Itxt 


and hjt 


buflirt 




.NLIST 


BEX 


AC 


■ 




CODBEG : 


.ASCIZ 


<lB><12><7>/Job 


CODLEN 


« . - AC 




.ASCIZ 


<lB><12><7>/Job 




.ASCII 


<lB><12><7>/Job 


PIGNAN: 


: .ASCIZ 






.ASCIZ 


<lB><12><7>/Job 




.ASCIZ 


<15><12><7>/Job 


CPLEU 


: .ASCII 


/Job Bonltorlng 


EUCOD 


: .ASCIZ 


/o/ 




.END 


START 



iConTtrt atatuB coda to maiaaga offaat 
;ConTert to aaaaaga addraaa 

-.Point to corract atataa aaaaaga 
; Point to ENT arg block to 
:Sand notification to oparator 

buff an 

;ENT arg block to aonitor a Una 

;Lina (Job) number to ba aonltorad 

; Addraaa of coaplatlon routina 

:ENT arg block to aand taxt 

;Lina nuabar to ba notlfiad 

: Addraaa of aaaaaga to ba aant 

;ENT arg block to gat prograa naaa 

;Lina nuabor. aubf unction 

; Addraaa to put 1AD60 naaa 

: Addraaa of input buffar (lADBO) 

;AddraBa of output buffar (ASCII) 

;Nuabar of chara to eonrart 

;&ADBO Talu* of prograa naaa 

:Cop7 of Banding infor 



haB baen initlalliad 



haa coaplatad LOGON / 
axacuting prograa / 

/PIGNAN / 

raturnad to INON / 

loggad off / 

coaplation routine arror / 



4.42 Acquiring another job's file context 

One job may acquire the file context of another job. This is principally intended for detached jobs (such as 
RTSORT) which operate as file servers, so that they may access files for the job they are servicing even if 
those files are on logical subset disks or are access restricted. 
The following EMT may be used to acquire another job's file context: 

EMT 375 

with RO pointing to an argument block of the following form: 

.BYTE 0.160 

. VORD j ob-number 

.WORD 

where job-number is the number of the job whose file context is to be acquired. 

The job which issues this EMT must have GETCXT privilege except in the case where job-number specifies 

the parent of the job issuing the EMT. 

On successful return from the EMT, the following actions have been taken: 

1. All channels for the issuing job which are opened to files on logical disks are purged. 

2. All devices mounted by the issuing job are dismounted. 
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3. The following items are copied from the target job, replacing the previous information for the issuing 

job: 

• ASSIGN commands 

• ACCESS command restrictions 

• Logical disk information 

• Mounted device information 

See the TSX-Plus User 'a Reference Manual for more information on detached jobs. See the TSX-Plua 
System Manager's Guide for more information on GETCXT privilege. 



Error 
Code 



Meaning 



Issuing job is not privileged to use this EMT 
Target job number is invalid or is not logged on 



Example 



EUBH 
BS 
STAIT : 



31 

1$: 



.TITLE 
.ENABL 
Dnionstrat* 
.NCALL 
.DSABL 
.GLOBL 

- 62 

- 10 
.GTLIN 
NOV 
CALL 
NOV 
NOV 
ENT 
BCC 
TSTB 
BGT 
.PEINT 
BE 

.PEINT 
BE 
NOV 
CALL 
NOV 
CALL 
.EXIT 



9t: 
AEEA: 
GETCXT : 
JOBNUN: 

STATUS : 
DEVNAN: 

BUFFEE 

PENPTl 

NOPEIV 

NOTON: 

AEEOW: 

COLETM: 

CELF: 



.BLKV 

.BYTE 

.VOED 

.VOED 

.WOED 

.EADBO 

.NLIST 

.BLEB 

.ASCII 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCIZ 

.ASCIZ 

.LIST 



GETCXT 
LC 
ENT to gat contaxt of another Job. 
.GTLIN. .EXIT, .PEINT, .ENTEE, .CSTAT, .PUESE. .TTYOUT 
GBL 
ACEDEC.PETEEO 



«BnFFEE,f PENPTl 

iBUFFEE.El 

ACEDEC 

EO.JOBNVN 

«GETCXT.EO 

37B 

1$ 

C#EEEBYT 

at 

iNOPEIV 
Ot 

»NOTON 
B( 

«'ESY, DEVNAN 
SHODEV 

«'EOE. DEVNAN 
SHODEV 



ENT error b^tt addreaa 

ASCII backapaco BS 

Proapt for lino f to check 

Get pointer to line 9 atrlng 

Conrert to number 

Put line nuBber in ENT arg block 

Point to ENT arg block to 

Get context of another Job 

Branch If no error 

PriTllege or no Job? 

Branch if requested line not logged on 

No priTllege for this ENT 

quit 

That Job not logged on 

Quit 

Locate SY flrat 

DeterMine and display ite doTlce 

Same for DE 



{General purpoae ENT arg block 

;ENT arg block to get Job context 

;Line nusber of Job in question 

;Eequired 

;.CSTAT channel status result 

;NaBe of temporary file 



10 

0,160 





0,0,0,0,0,0 

/DE TEMP FIL/ 

BEX 

81. 

/Get context of line number - /<200> 

/Sorry, you are not pririleged to run this program./ 

/Sorry, that Job is not currently logged on./ 

/ — /<r6><40><200> 

/:/ 

// 

BEX 
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.EVEN 
; Lat a^itMi tranilmtt derlc* aiflgrmtnti by opening 

J a tnporary lil« and u«t thd .CSTAT EMT. 

8H0DEV: .EHTEl #AREA,#0.fDEVKAM.fl ;Try to open twporary lilt 

BC8 9$ ;CiT« np on orror 

.CSIil f AREA, iO.f STATUS ;Try to got ehumol Info on fllo 

BCS 9$ :GiTO ap on error 

NOT DEVKAN.KO :leeoTer logical device naae 

CALL PETRBO ;Dieplay it 

.PRIKT #ARROir ;" — > " 

MOT 8TATUS+12,R0 ;RecoTer phyeieal device name 

CALL PETRBO jDieplay it 

.TTTOOT iBS ;Back up orer eapty unit niuber 

NOV STATUS+IO.RO ;RecoTer phyiical unit noaber 

ADD f'O.RO ; Convert to ASCII 

.TTYOUT ;Dliplay It 

.PRINT #COLRTN ; Format 

9$: .PURGE iO ;Throw avay temp file 
RBT0RN 

.END START 



4.43 Manipulating process windows 

The TSX-Plus process windowing facility allows the system to remember the contents and status of the 

terminal screen display and to redisplay windows as you switch between processes or on demand by programs. 

The process windowing facility also provides a print window function which allows you to print the contents 

of a window on a printer by typing a control character or by use of an EMT. Windows are only allowed on 

VT200, VTIOO, and VT52 series terminals. The contents and status of each window is stored in a named 

global region and you must have SYSGBL privilege in order to use process windows. See the TSX-Plue 

Uttr't Rtftrtnee Manual for more information on the use of windows and window related commands (SET 

WINDOW, SET PRINTWINDOW). 

Each job may have up to 26 windows active at one time. A window is identified by an ID number in the 

range 1 to 26. Two jobs may have windows with the same ID number without conflict. 

When windowing is turned on, the system monitors all characters sent to the terminal and maintains an 

updated screen image in memory. Terminal attributes such as line width, reverse/normal video, application 

keypad mode, etc. are saved along with line attributes (double wide, double high), and character attributes. 

The attributes retained for each character consist of blinking, bold, underlined, reverse video, and character 

set information (ascii, U.K. national, DEC supplemental, or graphics— line drawing). 

The most common use of windows is to completely refresh the display when switching among subprocesses 

to avoid the confusion of mixed displays. In addition, a keyboard command can be used to send a copy of 

the current window to a printer. 

For some special program applications, it may be useful to utilize multiple windows from the same job. 

System service calls (EMTs) are provided to create, select the current, delete, and print process windows. 

4.43.1 Creating a window 

The system service call (EMT) used to create a window has the form: 

EMT 375 

with RO pointing to an argument block of the following form: 

.BYTE 0.161 

.BYTE window-id, perm-flag 

.BYTE window-width. max-icroll 

.BYTE copy-id, copy- job 

.WORD 
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where window-id is a window identification number in the range 1 to 26 which identifies the particular job 
window. The global memory regions created for windows have names of the form WlNjji where jj is the 
job number and t is a letter which corresponds to the window ID (A=l,. . . ,Z=26). Different jobs may have 
windows with the same ID without conflict. 

Perm- flag should be either or 1. If it is zero (0), the window is temporary and will be automatically 
deleted when the program exits to the keyboard monitor (other than doing a chain). If perm-flag is 1, the 
window is permanent and is only deleted when explicitly requested (by the delete- window EMT, or by SET 
WINDOW OFF) or when the job logs off. 

Window-width is the width of the window in columns and should not exceed 132. (VT52 may use only 80.) 
Max-scroll is the maximum number of lines which are allowed to scroll off the window during a time when 
the window is disconnected from the terminal because a diff'erent subprocess has been selected. A value of 
zero (0) may be specified to disable any scrolling. If a value of 255 is specified, an unlimited amount of 
scrolling is allowed. 

The copy-id and copy-job parameters can be used to cause the system to copy certain window information 
from another window as it is initializing the new window. If copy-id and copy-job are both zero, no informa- 
tion isi copied from another window and the supplied values (or default values) are used for the new window. 
If copy-id is non-zero, is is used as the id of the window from which the information is to be copied. If 
copy-job is non-zero it is the number of the job that owns the window from which the information is copied. 
If copy-job is zero, the current job is assumed. The following information is copied: 

1. The number of columns per line. 

2. The maximum allowed number of lines to be scrolled while switched to a different process. 
5. 80 or 132 column mode. 

4. Light or Dark (normal or reverse video) mode. 



Error 

Code 
_ 



Meaning 



Window management not included in system generation or invalid 
EMT argument block. 

Maximum allowed number of windows are already in use. Increase 
value of MAXWIN sysgen parameter. 

Unable to create global memory region for window. Job may not 
have SYSGBL privilege or you may need to increase the value of 
the NCR sysgen parameter, or there may be insufficient memory 
space available. 



Creating a window allocates a window control block and a global memory region for the window, 
window contents are set to all blank. 



The 



Example 



.TITLE WINDOir 

: Dsaonttrata ust of multlpl* process windows. 

.DSABL GBL 

.ENABL LC 

.MCALL .PRINT,. EXIT,. TWAIT 
ElMYT » 62 ;EMT orror cod* addrvss 

; Croat* and Initlalli* contents of 10 windows 
STAIT: MOV #10., Rl ;Inlt window nuabor 
II: MOVE il.¥INIDl ;Polnt to n*xt window 
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NOV 

ENT 

BC8 

NOVB 

NOT 

ENT 

BCS 

NOT 

DEC 

iSL 

.PlIMT 

SOB 



#M1IWIN,E0 -.Point to EMT »rg block to 

S76 :CToatt a window 

NAKEBl :Branch on orror 

E1,WINID2 ;Point to ntxt window 

fSELWIN.aO ;Point to ENT arg block to 

376 :S«loct ■ window 

8ELES1 iBruich on orror 

11,1,2 :Cop7 window nuabor 

12 ;0 indox 

12 ;ConTort to word Indox 

WIKTXT(&3} ;Wrlt» ooaothing to oaeh scroon 

11,1$ ;Eapaat through tan wlndowa 



; Cyla throogh tha windowa lor paaudo-aniMtlon. 



21: 
221: 



Mow 



S$: 



NAIEU 

SELEU 

DELEU 
DSPEU 



NAIVIH 

VINIDl 



SELVIN 
WINID2 

DELWIM 

WINID3 

TINE: 

KVINS: 

AESA: 

WIHIXT 



LIL 
L2L 
LSL 
L4L 
L6L 



NOT 
NOT 
NOTB 
NOT 
ENT 
BCS 
.T¥AIT 
SOB 
BGT 
CNP 
BEQ 
SOB 
dalata 
NOT 
NOT 
NOVB 
NOT 
ENT 
BCS 
SUB 
BGT 
BE 
: NOT 

BE 
: NOT 
BE 
: NOT 
: NOTB 
ADD 
NOVB 
NOVB 
NOVB 
.PlIHT 
.EXIT 
.BYTE 
.BYTE 
.BTTB 
.BYTE 
.BYTE 
.VOID 
.WOED 
.BYTE 
.BYTE 
.WOID 
.BYTE 
.BYTE 
.WOED 
.WOED 
.BLEW 
.WOED 
.RLIST 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 



*6.E2 

#10.. 11 

11.WINID2 

fSELVIN.&O 

S7G 

8ELE&E 

«AEEA.ffTINE 

NWINS.El 

22$ 

NWINS.t2 

2$ 

E2.2$ 
half the windows 

*2.NVINS 

#9.. El 

El.WINIDS 

fDELVIN.EO 

376 

DBLE&E 

NWINS.El 

3$ 

2$ 

tNETXT.EO 

DSPEEE 

fSETXT.EO 

DSPEEE 

iDETXT.EO 

t«EEEBYT.El 

*'0,£1 

El.ECl 

E1.EC2 
El. ECS 



o.iei 





80. 







1.181 

0.0 



2.161 

0.0 

0.18. 

1 

10 



:Loop 5 tlaaa with all windows 

;Inlt window nuabar 

; Point to naxt window 

;Point to ENT arg block to 

:Salact naxt window 

: Branch on arror 

:Dala7 a littla bit 

;8tap to naxt window 

;And rapoat 

; Already doing halft 

;Branch if ao 

:Eopeat all windowa 6 ti»a 

-.Only do half of them 
;Dalete odd numbered windowa 
■.Point to next window 
:Point to ENT arg block to 
;Delate a window 
{Branch on arror 
■.Point to next window 
:Eepeat through E windowa 
;Eepeat reat foroTor 

;Point to error Bessage 

;Go display arror 

;Point to arror meaaage 

;Go diaplay arror 

'.Point to arror Baasaga 

;6et arror code 

;ConTert to digit 

; Store in all 

; output 

; atrlngs 

{Display arror Bessage 

',BKT arg block to Bake window 

{Window id nuaber 

{Temporary window 

{Narrow window 

{No acrolling restrictions 



{ENT arg block to select window 
{Window id nuBber.O 



{ENT arg block to delate window 

{Window id nuaber.O 

{TlBo delay in ticks (arbitrary) 

{Window id incraaant 

{General ENT arg block 

LIL , L2L . LSL . L4L . LSL , LEE , LiE , LSE . L2E . LIE 

BEX 



<12> 

<12><12> 

<12><12><12><12> 

<12><12><12><12><12><12> 



/ «/<200> 
/ •/<200> 
/ •/<200> 
/ •/<200> 



<12><12><12><12><12><12><12>/ 



*/<200> 



4.43. MANIPULATING PROCESS WINDOWS 



75 



LEI 




.ASCII 


<12><12><12><12><12><12><12>/ 


«/<200> 


L4E 




.ASCII 


<12><12><12><12><12><12> 


/ 


♦/<200> 


LSI 




.ASCII 


<12><12><12><12> 


/ 


*/<200> 


L21 




.ASCII 


<12><12> 


/ 


*/<200> 


Lll 




.ASCII 


<12> 


/ 


•/<200> 


METXT: 


.ASCII 


/Window creation •rror #/ 






ECl: 


.ASCIZ 


/o/ 






8ETXI : 


.ASCII 


/Ylndov telvctlon error #/ 






EC2: 


.ASCIZ 


/o/ 






DETXT : 


.ASCII 


/Window deletion error #/ 






ECS: 


.ASCIZ 
.LIST 


/o/ 

BEX 










.END 


START 







4.43i.2 Selecting a current window 

When this EMT is executed, the terminal screen is cleared and the selected window is drawn on the screen. 
The EMT argument block used to select the current window has the form: 

.BYTE 1.161 
.BYTE window-id. 
.WORD 

where window-id is the window identification number as specified when the window was created. A window- 
id value of zero (0) ha^ a special meaning: it causes windowing to be disabled for the job but the contents 
of all existing windows are retained and may be reselected later. 



Error 
Code 



Mcar^ing 







Window management not included in system generation or invalid 

EMT argument block. 

Unable to locate window with specified window-id. 



4.43.3 Deleting windows 

The EMT argument block used to delete a window has the following form: 



.BYTE 
• BYTE 



2,161 
window-id. 



where window-id is the identification number of the window to be deleted. There are two special values for 
window-id which may be used with this EMT: a value of zero (0) causes all temporary windows for the job 
to be deleted; a value of 255 (decimal) causes all windows for the job, both temporary and permanent, to 
be deleted. 

The global memory region used by a window is freed when the window is deleted. 



Error 
Code 



Meaning 



Window management not included in system generation or invalid 

EMT argument block. 

Unable to locate window with specified window-id. 
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4.43.4 Suspending window processing 

Window processing may be suspended to allow characters to be sent to the terminal which are not processed 
by the window manager. If the job does not have a currently active window, the suspend and resume 
functions have no effect. The EMT 375 argument block to suspend window processing is: 

.BYTE 3.161 



4.43.5 Resuming window processing 

Window processing which has been suspended may be resumed by EMT 375 with the following argument 
block: 

.BYTE 4.161 



4.43.6 Printing a window 

The contents of a window may be printed by issuing EMT 575 with the following argument block: 



.BYTE 
.BYTE 



B.161 
vindov-id.O 



where window-id is the id number used when the window was created. The WINPRT program must be 
executing in order for the window to be printed. 



Error 
Code 



Meariing 



Window management not included in system generation 
Unable to locate window with specified window-id 
WINPRT program not running 



4.44 Svs^itching Between Subprocesses 

The following EMT allows a running program to switch terminal control between subprocesses as if a CTRL- 
W-digit sequence had been typed. The EMT has two functions: it initiates new subprocesses, and switches 
terminal control between processes. 

The form of the EMT is: 



ENT 375 

with RO pointing to the following argument block: 

.BYTE Bub-f unction. 162 

.BYTE subprocesB-number.O 

.BYTE return-process. initiate-only 

.WORD command-f ile-pointer 

.WORD 
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If tub-function is 1 the EMT initiates a new subprocess and optionally switches terminal control to the 
subprocesses. Error code 5 is returned if the specified subprocess is already active. If sub-function is 2 
the EMT switches terminal control between already- active subprocesses. Error code 6 is returned if the 
specified subprocess is not already active. If sub-function is (zero), the EMT initiates a new subprocess if 
the specified subprocess is not already active (and switches to it if the initiate-only flag is (zero)), or just 
switches control to the subprocess if it is already active. 

Subprocess-numbcr indicates the subprocess number and is analogous to the digit typed after CTRL-W 
when manually switching between subprocesses. The value must be in the range to MAXSEC (a TSGEN 
parameter). If the number is too large, then the EMT returns with error code 2 and MAXSEC in RO. 
Speciiying (zero) for tubproccts-numbcr switches back to the primary process (just as typing CTRL-W-0). 
If a -]L (minus one) is specified for tubproccte-numbtr , the system locates the first unused subprocess number 
and uses it. The number of the selected subprocess is returned in RO on completion of the EMT. 

Rcturn-procest indicates which process is to be returned to when the process initiated by the EMT logs off. 
Speciiy (zero) to cause return to the primary process; specify 1 to return control to the process which is 
executing the EMT to initiate the subprocess. 

Initiate-only controls whether the terminal connection is switched to the subprocess. If initiate-only is 
(zero), the subprocess is initiated (if it has not already been initiated) and terminal control is switched to 
the subprocess. If initiate-only is 1 the subprocess is initiated but terminal control remains with the current 
process. 

Command-file-pointer is the address of an ASCIZ string containing the file specification of a command file to 
be executed when the subprocess is initiated. This command file executes without start-up privilege following 
any other start-up command file specified with the SET SUBPROCESS/FILE command. If command-file- 
pointer is (zero) no command file is executed. 

The return-process, initiate- only, and command-file-pointer parameters axe only used when initiating a new 
subprocess. They are ignored if this EMT is used to switch between subprocesses that have already been 
initiaited. 

The following error codes can be returned by this EMT: 



Error 




Code 


Meaning 


1 


You are not authorized to use subprocesses 


2 


Specified subprocess number is too large 


3 


All of your subprocesses are already active 


4 


Insufficient memory space available for process 


5 


Specified subprocess has already been initiated 


6 


Specified subprocess has not been initiated 



Example 

.TITLE SUBP&C 

D«monitration of the us* of tho TSX-Plua BNT to Initiate ■ubprocoaaos 

.MCALL .PRINT,. EXIT,. TWAIT 
.GLOBL PRTDEC 
.DSABL GEL 



EUBYI > 52 ;ENT orror bTto add^osi 

START: MOV «SITBPRC,RO ;Point to EMT arg. block to 
21 : ENT 376 ;Intiatt aubprocaia 
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»|: 



SUBPKC: 



E&ilS: 
SIITFL; 



BCC 

MOVB 
.PIIKT 

NOV 

CALL 

.EXIT 

.HLIST 

.BYTE 

• BTTB 

.BYTE 

.VOID 

.WOIS 

.ASCII 

.ASCIZ 

.EVEN 

.END 



9$ 

•*E&&BYT,-(SP) 
«E&£IS 

(sp)*.ao 

PETDEC 

BEX 

1,162 

1.0 

1.1 

STETFL 



/TSUBFEC-F-EMT 



;Bruich If 01 

; Fetch EHT •TTor cod* 

;"EMI trror ii:" 

:I«trlaT* error coda 

:Displa7 it 

:And txLt 

:EHT arg. block to initiato aubprocoaa 
:numbar 1 

;Iatarn to atartlng procaaa and init. only 
:Startup coaaajid lilo 

•rror la: /<200> 



/SY:SUBP1C.C0H/ :F11* apac. for atartup cob file for aubproc, 



8IAET 



4.45 Mounting Logical Disks 

The following EMT allows logical disks (LD's) to be mounted from within running programs just as if 
MOUNT command was used. The form of the EMT used to mount a logical disk is: 



EMT 



375 



with RO pointing to the following argument block: 

.BYTE Chan. 163 

.BYTE ld-\mit .read-only-flag 

.WORD lile-name-pointer 

where chan is the number of an I/O channel which must be closed at the time that the EMT is executed. 
This channel is used during EMT processing to access the file to which the LD unit is being associated. The 
channel will be closed on return from the EMT. Ld-unit is the binary value of the LD unit number that is 
being mounted; it must be in the range (zero) to 7. Read- only- flag is (zero) to allow both reads and writes 
to take place to the LD unit. Set read-only-flag to 1 to dballow writes to the LD unit. File-name-pointer 
is the address of a four-word block of data containing the RAD50 device name, file name, and extension, of 
the file with which the LD unit is to be associated. The specified LD unit must not be in use (associated 
with a file) at the time that this EMT is executed. 

The following error codes can be returned by the EMT: 



Error 




Code 


Meaning 





Channel provided is already open 


1 


Invalid logical disk unit number (must be 0-7) 


2 


Logical dbk support not generated into system 


8 


Logical dbk unit is already associated with a file 


4 


Invalid file specification (null device or file) 


5 


Invalid logical unit number nesting 


6 


Unable to open specified file 



Example 
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•TITLE MNTLD 

DsBonittratlon of the us* of tha TSX-Plus ENT to mount a logical diak. 

.NCALL .PRINT. .EXIT, .TVAIT, .CLOSE 

.GLOBL PITDEC 

.DSABL GBL 



EULBTT 



62 



:ENT arror byt* add^aaa 



STAIT : 


.CLOSE 


«0 




.CLOSE 


»1 




NOV 


«NNTLD6,R0 




ENT 


376 




BCS 


11 




NOV 


»NNTLD6,R0 




ENT 


S7E 




BCC 


2$ 


It: 


NOVB 


•«ERRBYT,-(SP) 




.PRINT 


iRRRIS 




NOV 


(SP)*,RO 




CALL 


PRTDEC 


2$: 


.CLOSE 


»0 




.CLOSE 


«1 




.EXIT 






.NLIST 


BEX 


NNTLDG: 


.BYTE 


0,163 




.BYTE 


6,0 




.WORD 


LD6NAN 


KNTLDfl: 


.BYTE 


1,163 




.BYTE 


6,0 




.WORD 


LD6NAN 


LD6NANI: 


.RAD50 


/DUBJNOWRIDSt/ 


LD6NAM: 


.RADEO 


/DU6SYSN0NDSX/ 


EUIS: 


.ASCII 
.EVEN 


/TNNTLD-F-ENT 




.END 


START 



Inaura channel la eloaed 

Insure channel is closed 

Point to ENT arg. block to 

Nount LD6: 

Branch if not OK 

Point to ENT arg. block to 

Nount LD6: 

Branch if OX 

Fetch ENT error code 

"ENT error Is:" 

RetrloTO error code 

Display It 

Close channel 

Close channel 



;ENT arg. block to 
; Nount LD6: 

;ENT arg. block to 
; Nount LD6: 

;. RADEO of file to uount as LD6: 
;.RAD60 of file to Bount as LD6: 



/<200> 
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Chapter 5 



Shared File Record Locking 



TSX-Plus allows several programs to have the same file open simultaneously. In order to control access to 
such files, TSX-Plus provides system calls to lock shared files and records within shared files. Through the 
record locking facility a program may gain exclusive access to one or more blocks in a file by locking those 
blocks. Other users attempting to lock the same blocks will be denied access until the first user releases the 
locked blocks. The TSX-Plus shared file facility also provides data caching on blocks being read from shared 
files. 

Note that shared file access protection is only meaningful for cooperating jobs requesting shared access. This 
scheme does not prevent other jobs from opening or writing to files if those jobs do not adhere to the file 
sharing protocol. 

The usual protocol for updating a shared file being accessed by several users is as follows. 

1. Open file, 

2. Tell TSX-Plus that file is shared. 

5. Lock all blocks in file which contain desired record. 

4. Read locked blocks into memory. 

5. Make update to record. 

6. Write updated blocks to file. 

7. Unlock blocks. 

8. Repeat steps 3-7 as needed. 

9. Close file. 

Use of shared files and record locking requires RLOCK privilege. 

DIBOL record locking procedures 

Subroutines to control record locking from within DIBOL programs are provided with TSX-Plus. These are 
discussed in Appendix D. 

Record locking from other languages 

Record locking may be interfaced to other languages with appropriate subroutine calls. Record locking under 
COBOL-Plus is built into the run-time library provided with COBOL-Plus. The remainder of this chapter 
describes the techniques used to control shared file access and record locking. 

81 



82 



CHAPTER 5. SHARED FILE RECORD LOCKING 



5.1 Opening a shared file 



Before a file can be used with shared access it must be opened by using a standard .LOOKUP EMT. After 
the file has been successfully opened, the following EMT may be used to declare the file to be opened for 
shared access. The form of this EMT is: 



ENT 



375 



with RO pointing to the following argument area: 



.BYTE 
.WORD 



Chan, 125 
access-code 



where chan is the number of the I/O channel open to the desired file and accctt-code is a value indicating 
the type of access protection desired for the file. The following access codes are recognized: 



Code 


Protection 


Access 





Exclusive 


Input 


1 


Exclusive 


Update 


2 


Protected 


Input 


8 


Protected 


Update 


4 


Shared 


Input 


5 


Shared 


Update 



The access code specifies two things: 

• the type of access that you intend to make to the file (input only or update) and 

• the type of access that you are willing to grant to other users of the file. 

There are three protection classes: 

EXCLUSIVE access means that you demand exclusive access to the file and will allow no other users to 
access the file in any fashion (input or update). 

PROTECTED access means that you will allow other users to open the file for input but wish to prohibit 
any other users from opening the file for update. 

SHARED access means that you are willing to allow other users to open the file for both input and update 
access. 

When this EMT is executed, TSX-Plus checks your specified protection mode and access type with that 
previously declared for the file by other users. If an access conflict arises because of your specified access 
characteristics an error code of 4 is returned for the EMT. If no access conflict is detected, your specified 
access code is saved with the file and will be used to check for conflicts with future shared access requests 
issued by other users. 

Normally all files that are declared to TSX-Plus using this EMT are enabled for use of the data caching 
facility (see description below). However, in some cases it may be desirable to suppress data caching for 
certain files. For example, sequential access files usually benefit little from data caching and enabling data 
caching for these files causes the data cache buffers to be used non-productively when they could be providing 
a better service for other types of files. To disable data caching for a file set bit 8 (octaJ 400) in the access- 
code word. When shared access is declared with bit 8 set, new data is not brought into the data cache when 
the file is read. However, if the data being read is already stored in the cache because of a read by another 
user, it is used. When data being written to a file is currently stored in the cache, the data in the cache is 
updated even if the file is declared to be non-cached. 
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It is possible to have several channels simultaneously open to different shared files. The exact number of 
channels that can be open to shared files and the total number of shared files that may be opened are 
speciJBed when the TSX-Plus system is generated. 

Once all access to a shared file b completed, the I/O channel should be closed using the standard .CLOSE 
or .PURGE EMTs. See the next section for information about saving the status of a channel that has been 
opened to a shared file. 

The error codes that can be returned by this EMT are listed below: 



Error 
Code 



Meaning 



Job does not have RLOCK privilege or system does not include 
shared-file support 

Channel has not been opened to a file. 

Too many channels opened to shared files. 

Too many shared files open. 

File protection-access conflict 



Exaiaple 



.TITLE SNA&ED 

.ENABL LC 
: Thii: program eoopcratai vlth tht axaapla prograa (SHAEB2) In tht 
; following stetlon to doKonttrata ahartd 211a accaaa protaction. 

.MCALL .PilNT, .6TLIN, .TWAIT. .EXIT, .EEADW 

.NCALL .LOOKUP. .CLOSE. . SAVESTATUS , . iBOPEN . .PUIGB 



KUBYT 
BXUP « 
PUN " 
BUFSIZ 
START : 



II : 



62 



2$: 



3$: 



*$ 



61: 



' 2E6. 
.LOOIUP «A&EA.«0,*SH£1 



BCC 

.PRINT 

.EXIT 

NOV 

MOV 

ENT 

BCC 

JNP 

.EEADW 

BCC 

.PRINT 

.EXIT 

.PRINT 



it 

»LKPERR 



;ENT arror byta 

:Sharad flla aeeaii coda: Excluiira, Updata 

:Sharad fila aceaaa coda: Protactad, Input 

;Kuabar of vordi In a diak block 

:Opan SHRi.DAT 

; Branch if OK 

; Lookup arror aaaaaga 



«EXirP . <S}aFIL+2> :8at ExcluaiTa, Updata aceaaa 
«SHRFIL.RO :Point to ENT arg block to 
376 '.Daclara SHRi.DAT ao a aharad fila 

;vith ExcluaiTa and Updata aceaaa 
; Branch if aharing OK 
■.Explain tha arror and quit 
ffARBA.«0,*BUFFER,#BUFSIZ,«0 :Raad block of SHRi.DAT 
3( :Branch if raad OK 

«ROVERR ;Sa7 thara vaa a rand arror 



at 

ENTERR 



«BUFFER 



: Print out tha fila (auat hara or 200 byta) 



.SAVESTATUS f AREA,«0.«BLOX1 ;SaTa ehannal atatua for ranaa 



BCC 4t 

.PRINT »SVSERR 

.EXIT 

NOV »SAVSHR.RO 

EMT 376 

.PURGE #0 

.LOOKUP «AREA,iO,«SHR2 



BCC 

.PRINT 

.EXIT 

NOV 

NOV 

EMT 



6t 

fLKPER2 



; Branch if aaTaatatua OK 
;SaTaBtatua arror Boaaaga 

; Point to ENT arg block to 

;SaTa aharad fila atatua 

;Purga tha ehannal for rauaa 

iOpan SHR2.DAT 

: Branch if OK 

;8a7 bad lookup on SHR2 



fPRIN.<SHRFIL+2> ;Sot Sharad. Input aceaaa 
«SHRFIL,RO : Point to EMT arg block to 
376 :Daelara 8HR2.DAT ae a aharad fila 
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7$: 



;Thlt J 



ENTE&2: 
ENTEU: 



AIEA: 

BLOKl: 

FILNim 

TIME: 

SH&EBA 



smi: 

SH&2: 
8KIFIL 

8AVSK1 
NOTOPN 
XSSCHN 
XSSFIL 
AXSCON 
SHllNN 
SH&2NM 
UPEU 
LKP£a2 
SVSE&i 
IDWEEl 
1DWE&2 
PIONPT 



P&MPT2 
BUFFEi 



BCC 
JNP 
.IKADV 
BCC 
.PtIHT 
.EXIT 
.PEIHT 
•PlIHT 
.TWAIT 
.PUIGB 
.GTLIN 
ob vlll 
.lEOPBN 
.KEADV 
.PlIHT 
.CLOSE 
.EXIT 
NOV 
NOVB 
DEC 
ASL 
.PUNT 
.PUNT 
.EXIT 
.BLXW 
.BLEV 
: .WOIO 
.¥010 
: .VOID 
.VOID 
.VOID 
.VOID 
.NLIST 
.1AD60 
.UD60 
: .BYTE 
.VOID 
.BYTE 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.ASCII 
.ASCII 
.ASCIZ 
.ASCII 
.BUV 
.END 



el ;Branch on no trror 

EMTE12 sSay orror on SH12 oharlng 
tAlEA.fO.fBUFFEl.fBDFSIZ.fO ;load block of SH12.DAT 
71 : Branch If road 01 

ilDVE12 ;Sa7 road orror on SH12 



fBITFFEl 
iPlOKPT 
«AlEA.fTINE 
fO 

iBirFFEl,«Plf(PT2 
bo aoapondod for 
iAlEA.iO.ffBLOEl 
iAlEA.ffO.iBDFFEl 
iBUFFEl 
ffO 

ffSiai2NN,FILNUK 

flEl&BYT.lO 

10 

10 

SHlElldO) 

FILNUM 



10 

6 

SHllNN 

o,so.«eo 

NOTOPN 

XSSCKN 

XSSFIL 

AXSCON 

BEX 

/DI SHSl 

/DI SH12 

0,126 

1 

0.122 



-.Print out tho contonti (1 lino, nail fillod) 

;Sa7 it'a tlao to try co^>anlon prograa 

;Vait SO aoconda to ran othor prograa 

;Now. roloaao SH12 

;Valt for roturn from aabprocoaa 

output whllo gono to aubprocoaa 

;And got SHll back 

.tBUFSIZ.il :load in aoeond block of SHll 

:And print it to proTO atatna vaa aaTod 

;loloaao SHll 

;Point to altornato fllo orror 

;Got tho orror typo 

;Zoro offaot 

:ConTort to word offaot 

; Print tho appropriate orror aoaaago 

;And tho filo naao 

;ENT arg block aroa 
:SaToatata8 aroa for SHll. DAT 
;Fllo naao for orror aoaaago 
;SO.aoc • SO.tica/aoc 
;Polntor to ENT orror aoaaagoa 



DAT/ 
DAI/ 



:Filo doBcriptor for SHll. DAT 

;Filo doacrlptor for 8H12.DAT 

;ENT arg block to dodaro aharod filo 

:ExcluaiTO Dpdato aeeoaa (GETS CHANGED) 

;ENT arg block to aaro aharod filo atatna 

/Attoapt to aharo onoponod channol/<T><200> 

/Too aany channola oponod to aharod filta/<7><200> 

/Too aany aharod filoa opon/<7><200> 

/Attoapt to protoet alrtady protoctod aharod fllo/<7><200> 

/: SHll. DAT/ 

/: SH12.DAT/ 

/Lookup orror for SHll.DAT/<7> 

/Lookup orror for SH12.DAT/<7> 

/Error oceurrod attoapting to oaTO 8H11.DAT fllo otatuo/<7> 

/Error oceurrod whllo roadlng 8Hll.DAT/<7> 

/Error oceurrod whllo roadlng SH12.DAT/<7> 

/Go to a aubprocoaa and IDN 8HA1E2 which atto^ita /<16><12> 

/to aharo tho aaao filoa (SHll. DAT. 8H12.DAT} ./<16><12> 

/Valting SO aoconda /<7> 

/Vhon you haTO roturnod, hit lETUlN to eontinno/<200> 

BUFSIZ 

STAIT 



See also the example program SHARE2 in the section on saving the status of a shared file channel. 



5.2 Saving the status of a shared file channel 

A standard .S AVESTATUS EMT may be used to save the status of a shared file channel. If this is done, all 
blocks that are being held locked in the file remain locked until the channel is reopened and the blocks are 
unlocked (see below). 

When using a single channel number to access several shared files it is convenient to initially do a .LOOKUP 
on each file, then declare the file to be shared (EMT above), and then do a .S AVESTATUS. The channel 
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being used to access the set of files can then be switched from one file to another by doing a .PURGE 
followed by a .REOPEN. However, before doing the .PURGE, TSX-Plus must be told that you wish to save 
the shared-file status of the file, otherwise all locked blocks will be unlocked and the file will be removed 
from the shared-file list. The form of the EMT used to perform this function is: 



ENT 



375 



with RO pointing to the following argument block: 

.BYTE Chan. 122 

where chan is the I/O channel number. The effect of this EMT is to suspend the connection between the 
shared file information table and the I/O channel. Any blocks that are currently locked in the file remain 
locked until the channel is reopened to the file (by using a standard .REOPEN EMT). After saving a shared 
file status, the channel may be freed by using a .PURGE EMT. 

If the same file is opened more than once concurrently using different channels in the same program, and the 
channels are suspended by using the preceeding EMT, the system reassociates the correct shared-file context 
with the channel when it is reopened by matching the channel number used with the .REOPEN EMT with 
that used with the suspend EMT. Thus if the same file is opened more than once using different channels 
in the same program and is used with record locking, it is important to use the same channel number when 
suspending the file and reopening it. It is all right to switch the channel number between suspending file 
access and reopening it if the file is only open on one channel at a time within the program. 

Example 



.TITLE SHA&E2 

.ENABL LC 
; Thli prograa cooperatet vlth tht txuiplt progrut (SHARED) in tht 
; prtTtLout lectlon to daaonttrate iftTing of tharod flla ■tatui vlth 
; tht .SAVESTATUS ENT. 

.NCALL . LOOKUP,. PIINT,. EXIT,. lEADW 

.NCALL . CLOSE,. TVAIT 
EUBYT - 62 :EMT orror byt* 

BUFSIZ - 266. :Slx« of diik fil* block 

Try to open a fllo which la accatt locked 

Branch If 01 

8a7 couldn't gat tha flla 

Co on to ttj aacond flla 

Point to ENT arg block to 

Daclara flla for aharad aecaaa 

If got tha flla, branch to raad It 

Eli a explain why 

Say we can't ahare SKEl 

leleaae channel 

Go on to next file 

«BUFSIZ,iO :Try to raad block of SHil 

Dlaplay it for klcka 

Dona with SHil for the Boaent 

Try to open SH12 

Branch if 01 

Say ve couldn't oTon open it 

Go on to try 8HK1 again 

Point to ENT arg block to 

Declare file for ahared acceaa 

Aceeaa Input, Update to ahov lockout 

though va don't write in thla example 
Branch if we can ahare it 
Explain why not 
Say we will try again later 
Valt 6 aeeonda and 
Try again 



8TA1T 


.LOOKUP 


«A&EA,iO,iSH&l 




BCC 


11 




.PlINT 


iLKPRHR 




Bl 


3$ 


i$: 


NOV 


fSHRFIL.lO 




ENT 


376 




BCC 


2$ 




CALL 


EXPLE& 




.PEINT 


•INSHRl 




.CLOSE 


»0 




BI 


3$ 


3(: 


.lEADV 


iAEEA,iO,«BDFFE&. 




.PlINT 


«BUFFER 




.CLOSE 


#0 


3$: 


.LOOKUP 


*AEEA,«0,»SHi2 




BCC 


4$ 




.PlINT 


*LKPE&2 




Bt 


6$ 


4t: 


NOT 


*SH&FIL.10 




ENT 


375 




BCC 


6$ 




CALL 


EXPLE& 




.PlINT 


iAGAIN 




.TWAIT 


«A&EA,iTINE 




BI 


41 
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E$: 



6$: 



7$: 



101: 
111: 
EXPLEl: 



AKEA: 
SHiFIL: 



SKiEU: 



TIMS 

SKil 

SHia 

NOTOPN 

XSSFCH 

ZSSFOP 

AXSCON 

INSHIl 

LIPEU 

LKPEia 

AGAIN: 

STLLOK 

BUFFEI 



.lEADV 

.PIINT 

.CLOSE 

.LOOKUP 

BCC 

.PEINI 

.EXIT 

NOV 

EMT 

BCC 

CALL 

.PEINT 

Bl 

.lEADY 

.PUNT 
.CLOSE 
.EXIT 

NOVB 

DEC 

ASL 
.PUNT 

lETUlN 

.NLIST 

.BLIY 

.BYTE 

.VOID 

.VOU) 

.VOID 

.VOtD 

.VOED 

.VOID 

.UDEO 

.IAD60 

.A8CIZ 

.A8CIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.BLKV 

.END 



«A&EA,f0.fBnFFEi,tBDFSIZ,ffO ;l«&d block of SHia 

iBUFFEE ;ProTi th4t wt got It 

#0 :Don« with SHia 

iAEBA,«0.*SH&i :Tr7 SHil again 

7$ : Branch if it workod 

fLKPEEI, ;Sa7 wo eonldn't do It 

fSHIFIL.&O :Point to ENT arg block to 

376 ;D«clart oharod filt 

10$ ;Branch If OX 

EXPLEK :And oxplain tht orror 

f STLLOK :SaT It vat still lockod 

lit :And quit 

ffAKSA,«0.iBUFFEI,iBUFSIZ,il ;load in block 1 

ffBUFFER ;And dlaplay it 

«0 :Dono with 8H11 



;Flnd ont why can't ahart it 
;ConTOTt to itro indox 
;Mak« into word off tot 
:8a7 why wo couldn't got it 



:ENT arg block 

:ENT arg block to doclaro filt aharod 

;Accoii Shared, Updato 

: Shared filo orror aoaaago pointers 



•fEL&BYT.EO 

10 

10 

SH&EMdO) 

BEX 
10 

o.iae 

E 

NOTOPN 

XSSFCH 

X8SF0P 

AXSCON 

O.E.'OO. :6.Bec * 60. tics/sec 

/DK SHll DAT/ : Input file #1 naae 

/DK SKia DAT/ : Input file §2 naae 

/Cannot share unopened file/ 

/Too Ban7 channels opened to shared files/ 

/Too aany shared files open/ 

/Shared file protected b7 another Job/ 

/On first tr7 at SHll. DAT/ 

/Dnable to lookup SHll. DAT/ 

/Dnablo to lookup SKia.DAT/ 

/Can't access 8Hia.DAT. will tr7 again in 6 seconds/ 

/On second tr7 at SHll. DAT/ 



BDFSIZ 
STAIT 



: Input read buffer 



See also the example program SHARED in the section on opening a shared file. 

5.3 Waiting for a locked block 

The following EMT can be used to lock a specific block in a file. If the requested block is locked by another 
job, the requesting job will be suspended until the desired block becomes available. The form of the EMT 

is: 

ENT 376 

with RO pointing to the following area: 



.BYTE 
.WORD 



Chan. 102 
block 



where ehan is the number of an I/O channel that has previously been declared to be open to a shared file 
and block is the number of the block in the file to be locked. Other blocks in the file which were previously 
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locked remain locked. The maximum number of blocks which may be simultaneously held locked is specified 
when TSX-Plus is generated, A block number of -1 (octal 177777) can be used to request that all blocks 
in the file be locked. If several users request the same block, access will be granted sequentially in the order 
that Ithe requests are received. 



Error 
Code 



Meaning 



Job does not have RLOCK privilege or system does not include 
shared-file support 

Channel is not open to a shared file 

Request to lock too many blocks in file 



Example 



: Thill 
; ••€! 

EUBYT 
BUFSIZ 
8TAIT : 



1$: 



.TITLE LOCXW 
.BNABL LC 
program coopcratti with the exuipla program (LOCI) In tha naxt 
Ion to dtmonitrata aharad flla racord locking. 



2$: 

St: 



4t: 
El: 



61: 



.NCALL 

> 62 

> 3E6. 
.LOOKUP 
BCC 
.PRINT 
.EXIT 
NOV 
ENT 
BCC 
MOVE 
DEC 
ASL 
.PEINT 
.CLOSE 
.EXIT 
NOV 
ENT 



BCC 

CNPB 

BHI 

.PRINT 

BR 

.PRINT 

BR 

.PRINT 

.TWAIT 

NOV 

ENT 

BCC 

.PRINT 

BR 

.T¥AIT 

NOV 

ENT 

BCC 

.PRINT 

.READW 

.PRINT 

.READW 

.PRINT 



.PRINT, .EXIT, .TVAIT, .LOOKDP, .READW. .CLOSE 
;ENT arror coda byta 
;Word8 par dlik block 

»AREA,i0.iSHRl ;Opan SHRl.DAT 

1$ :Branch it OX 

«LIPERR ;Sa7 bad lookup 



«SHRFIL.RO 

875 

3$ 

««ERRBYT,RO 

RO 

RO 

SHRERR(RO) 

#0 

«L0CIW,RO 
376 



61 

•#ERRBYT,«1 

41 

iSFCNOP 

2$ 

iXSLIBL 

2$ 

•PRONPT 

«AREA,«SEC20 

tirNL0CI,RO 

376 

6$ 

iSFCNOP 

2( 

fAREA.«SEC10 

fCIWSHR.RO 

376 

8< 

«CHANGD 

iAREA.fO.iBDFFER, 

iBOFFER 

iAREA,iO,«BUFFER, 

*BUFFER 



:Polnt to ENT arg block to 
;Daclara aharad flla 
;Branch If OX 
;Get tha arror coda 
:Naka laro Indax 
;ConTart to word offaat 
;Prlnt tha arror maaaaga 
;GlTa back tha chaimal 

Point to ENT arg block to 

Lock block of SHRl.DAT 

(Job la anapandad until block arallabla 

to ba lockad) 

Branch vhan block la raady 

Which arror? 

Too many blocka lockad? 

Waan't opan to aharad fllal 

Glra up 

Too many lockad blocka In flla 

(Daflned by NXLBLX paramatar In TSGEN) 

Glra up 

Switch llnaa to attampt accaaa 

Walt 20 aeconda bafora unlocking 

Point to ENT arg block to 

Unlock a alngla block 

Branch If OX 

Waan't aharad fllal 

GlTa up 

Walt 10 aaconda for companion 

Point to ENT arg block to 

Chack for vrltaa to aharad flla 

If nona, wrap up 

Say va hara nav data 

iBUFSIZ.iO :Oat block 

Show currant contanta block 

«BUFSIZ,il ;Gat block 1 

Show contanta block 1 
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8t: 

DONE: 



klEk: 
8H&FIL: 

LOCIV: 

UNLOCI: 

CXVSHi: 



Stntl: 

SEC20: 

SECIO: 

MOIOPN 

XSSFCH 

XSSFOP 

AXSCON 

LIPEli 

SFCNOP 

XSLXBL 

CHANGD 

NOCHNG 

PiONPT 



BUFFEI 



Bl 

.PUNT 

.CLOSE 

.EXIT 

.NLIST 

.BLEV 

.BYTE 

.WOID 

.BTTE 

.¥OEI) 

.BYTE 

.¥01D 

.BYTE 

.WOU) 

.VOiO 

.WOU) 

.WOU) 

.UDBO 

.WOED 

.VO&D 

.ASCIZ 

.A8CIZ 

.iSCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCIZ 

.EVEN 

.BLKV 

.ENS 



DONE 

«NOCHNG 

«0 

BEX 

10 

0,12E 

4 

0.102 



O.llS 



0,121 

NOTOPN 

XSSFCH 
XSSFOP 
AXSCON 
/DI SHll 
0.20. 'CO 
0.10.*60 



;St7 nothing hai chuigad 
;Fr«« up channel 



;EKT arg block arta 

;ENT arg block to doclaro ahartd flit 

;Accaaa Sharod. Input 

;ENT arg block to lock tharod 111* block 

; Block nuabtr to bt lockod 

:ENT arg block to unlock aharod flla block 

;Block nuBbar to ba unlockad 

;ENT arg block to chock wrltea to aharod fila 

;Shartd illt trror mtaaaga tabla 



DAT/ ;Fllt naat to ba ahartd 

:20.aoc * 60.tlea/8oe 

;10.atc • eo.tlca/sac 
/Channal not opanod to ahartd fila/<7> 
/Too many channtla optntd to ahartd flltB/<7> 
/Too Bany ahartd filta optn/<7> 
/Fila prottctloB acctaa eonflict/<7> 
/Dnablt to optn SHll. DAT/ 

/Can't lock or unlock block not optn to ahartd flit/ 
/Can't lock so many blocka In ont flit/ 
/Data haa bttn vritttn to flit. Conttnta follow:/ 
/Data In flit la nnchangtd/ 

/Block In 8H11.DAT vlll rtaaln locktd for 20 ate/<16><12> 
/Go to anothtr lint and EON TLOCI to ttat lt/<7> 

BUFSIZ 
START 



5.4 Trying to lock a block 

This EMT is similar in operation to the previous EMT — it is also used to request that file blocks be locked. 
The difference is that if the requested block is already locked by another user the previous EMT suspends 
the requesting program whereas this EMT does not suspend the program but rather retxirns an error code. 
As above, a request to lock block #-1 is treated as a request to lock the entire file. If the block is available 
it is locked for the requesting user and no error is reported. The form of this EMT is: 



EHT 



375 



with RO pointing to the following argument area: 



.BYTE 
.WORD 



Chan, 103 
block 



where ehan is the number of the I/O channel associated with the file and block is the number of the block 
which is to be locked. 



Error 






Code 


Meariing 







Job does not have RLOCK privilege or system 
shared-file support 


does not include 


1 


Channel is not open to a shared file. 




2 


Request to lock too many blocks in file. 




S 


Requested block is locked by another user. 




4 


Entire file is locked by another user. 
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Examiple 



: Thli 
; prvTj, 

EUBTT 

ST AIT : 



1$: 



.TITLE LOCI 
.EN&BL LC 
prograB eooptratti with the •xaapl* prograa (LOCEW) in th* 
out ■action to daaonatrato aharad fila racord locking. 
.NCALL .PEINT. .EXIT. .VRITV, .TWAIT, .LOOIUP. .CLOSE 
;Brror byta addraaa 
iAREA.fO.ffSK&l ;Tr7 to opan SHKl.DAT 
1$ ;Branch If 01 

iLKPE&l :Sa7 va couldn't opan 



2$: 
SI: 



41: 
SI: 

ei: 



AREA: 
SHii: 
SHEFIL: 

LOCI: 

tniLALL: 

TINE: 
SHIEU: 



SFCNOP 
XSSFCN 
XSSFOP 
AXSCON 
LIPE&& 
WAITN6 

60BACI: 
NOPNSF: 
XSLKBL: 

BOFFEi: 

BUFSIZ 



' 63 

.LOOKUP 

BCC 

.PilNT 

.EXIT 

MOV 

ENT 

BCC 

NOVB 

DEC 

ASL 

.PUNT 

.CLOSE 

.EXIT 

NOV 

ENT 

BCC 

CNPB 

BLO 

BEQ 

.PKINT 

.TVAIT 

Bl 
.PUNT 

Bl 
.PlINT 

Bl 
.irilTW 

NOV 

EMT 
.PUNT 

Bl 

.NLIST 

.BLKV 

.lADEO 

.BYTE 

.WOIO 

.BYTE 

.VOID 

.BYTE 

.VOID 

.VOID 

.VOID 

.VOID 

.VOID 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.EVEN 

.ASCII 

.ASCIZ 



fSKlFIL.lO :Polnt to ENT arg block to 

376 :Daclara aharad flla 

SI :Branch if OK 

•iEllBYT.lO ;6at arror typa 

10 ;ConTart to laro Indax 

10 ;Naka Into word offaat 

SHlEll(lO) iDlaplay tha arror tjpa 

#0 ;lalaaaa tha channal 

:And glra up 

f LOCK, 10 sPolnt to ENT arg block to 

S7B :Tr7 to unlock block 

«| ; Branch if OK 

•»EllBYT.«a :Vhlch arror vaa it 

41 ;Vaan't opan to ahara filaT 

61 ;laquaBt to opan too aanj blocka in filaT 

*VAITN6 :Block lockad by anothar uaar 

•AlEA.fTINE ;Vait 3 aaconda 

31 ;And try again 

iNOPNSF :Not opan to aharad flla 

2| ;GiTa up 

tXSLKBL ;Too many blocka lockad in flla 

2| ;GlTa up 

#AlEA.iO,«BUFFBl,#BDFSIZ.iO :lawrita block 

«ITNLALL,10 :Polnt to ENT arg block to 

376 ;lalaaBa all blocka lockad by thla prograa 

fGOBACI ;NoaBaga: dona, go back to original Una 

21 ;Dona 
BEX 

10 :ENT arg block 

/DK SHll DAT/ ;NaMa of aharad flla 

0,126 :ENT arg block to ahara flla on chan 

3 ;Accaa8 Protactad, Cpdata 

0,103 :ENT arg block to leek block on chan 

;nuHbar of block to ba lockad 

0,101 ;ENT arg block to unlock all blocka on chan 

;(Only appliaa to blocka lockad by thla Job) 

:S.aac * 60.tica/aac 

:Fila aharing ENT arror tabla 



0,3. «60. 

SFCNOP 

XSSFCN 

XSSFOP 

AXSCON 

/Channal not opan to flla/<7> 

/Too many channala opan to aharad fllaB/<7> 

/Too many aharad fllaa epan/<7> 

/Sharad flla accaaa eonflict/<7> 

/Couldn't opan SHll.DAT/<7> 

/lequaatad block not arailabla for loeklng/<l&><12> 

/Vlll try again in S aaconda/ 

/Dona, log off and go back to original Una/ 

/Channal not opan to aharad flla/<7> 

/Attaint to lock too aany blocka In fila/<7> 



/(SHll) Thla Una vaa vrittan by tha program LOCK./ 
/ /<16><12> 

<.-BUFFEl^l>/2 :NuBbar of vorda to vrita 

BYTE 0,0 ;Safaty buapar 

END STAIT 
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5.5 Unlocking a specific block 

The following EMT is used to unlock a specific block in a file. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE Chan, 113 
.WORD block-munber 

where ehan is the number of the I/O channel opened to the shared file and block-number is the number of 
the block to be unlocked. 



Error 
Code 



Meaning 



Job does not have RLOCK privilege or system does not include 

shared-file support 

Specified channel not opened to a shared file 



Example 

See the example program LOCKW in the section on waiting for a locked block. 



5.6 Unlocking all locked blocks in a file 

The following EMT is used to unlock all blocks held locked in a file. The form of the EMT b: 

EMT 375 

with RO pointing to the following argument area: 

•BYTE Chan. 101 

where ehan is the I/O channel number open to the shared file. When this EMT is executed all blocks 
previously locked by the user on the shared file are unlocked. Blocks locked by the user on other files are 
not released nor are blocks of the same file that are locked by other users. 



Error 
Code 



Meaning 



Job does not have RLOCK privilege or system does not include 

shared-file support 

Channel is not open to a shared file. 



Example 

See the example program LOCK in the section on trying to lock a block. 
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5.7 Checking for writes to a shared file 

The following EMT can be used to determine if any other user has written to a shared file. The form of the 
EMT is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE Chan, 121 

where chan is the I/O channel number opened to the shared file. If no other user has written to the file 
since the file was opened by the user issuing this EMT or since that last time this EMT was issued for the 
file, the carry-flag is clear on return from the EMT. 



Error 
Code 







Meaning 



Job does not have RLOCK privilege or system does not include 
shared-file support or channel not opened to shared file 
Some other job has written to file since last check 



This EMT is useful when data from a shared file is being held in a program buffer. If no other user has 
written to the file, then the data is still valid. However, if the data in the file has been rewritten then it must 
be reread. The usual sequence of operations in this situation is to first lock the block whose data is in the 
program's buffer, then do the EMT to see if the file has been written to. If the file has not been modified 
the data in memory is valid and can be used, otherwise the block must be reread from the file. 

Example 

See the example program LOCKW in section 5.3 on waiting for a locked block. 

5.8 Data caching 

Data caching is a technique provided by TSX-Plus to speed access to files. When TSX-Plus is generated 
a certain number of 512-byte buffer areas may be set aside for data caching. These buffer areas are part of 
the resident system data area and are not associated with any particular job. There are two kinds of data 
caching: generalized data caching; and shared-file data caching. Both kinds may used automatically with 
minimal intervention on the part of the programmer or operator. Generalized data caching applies to all 
files on MOUNTed devices, while shared-file data caching applies only to files which have been declared as 
shared files. Generally, only one of these types is selected during generation of a TSX-Plus system. The 
following discussion applies to shared-file data caching. See the TSX-Plus System Manager's Guide for more 
information on data caching. 

Each time a request is issued to read a shared file, a check is made to see if the blocks being read are currently 
stored in the data cache. If so, the data is moved from the cache buffer to the program buffer and no disk 
I/O operations are performed. When data in the cache buffers is accessed, a use count is incremented. 
Periodically, the use counts for all buffers are divided by two. If the data blocks being read are not currently 
in the cache, the data is read from the disk into the program buffer and then it is moved into the cache 
buffers with the lowest use count. 

When a write operation is done to a file that is being cached, a check is made to see if the data being written 
is currently stored in the cache. If so, the cache buffers are updated. In any case the data is written to 
the disk. In other words, this is a write-through cache; the disk file is always updated and caching does not 
improve the performance of writes. 

All data files that are declared to TSX-Plus for shared access (using EMT S75 with function code 125) are 
eligible for data block caching regardless of their access protection type. Data caching on a shared file may 
be disabled by setting bit 8 (octal 400) in the access-code word of the EMT argument block when the file is 
declajred for shared access. Data caching is particularly effective for COBOL-Plus ISAM files. 
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Chapter 6 

Message Communications Facilities 



TSX-Pius provides an optional facility that allows running programs to send messages to each other. This 
message communication facility allows programs to send messages through named channels, check to see 
if messages are pending, and suspend execution until a message is received. TSX-Plus provides EMTs for 
each of these operations which are described below. Use of named message channels requires MESSAGE 
privilege. 

6.1 Message channels 

Messages are transferred to and from programs by using TSX-Plus Mtttagt ChanneU. A message channel 
accept!} a message from a sending program, stores the message in a queue associated with the channel and 
delivera the message to a receiving program when requested. Message channels are totally separate from 
I/O channels. 

Each message channel is identified to the sending and receiving programs by a one to six character name. 
The total number of message channels is defined when TSX-Plus is generated. The names associated with 
the channels are defined dynamically by the running programs. A message channel is said to be active if any 
messages are being held in the queue associated with the channel or if any program is waiting for a message 
from the channel. When message channels become inactive they are released and may be reused. 
Once a message is queued on a channel, that message will remain in the queue until some program receives 
it or the TSX-Plus system is halted. A program may exit after queuing a message without affecting the 
queued message. This allows one program to leave a message for another program that will run later. 

6.2 Sending a message 

The following EMT is used to queue a message on a named channel. If other messages are already pending 
on the channel, the new message is added to the end of the list of waiting messages. The sending program 
continues execution after the EMT and does not wait for the message to be accepted by a receiving program. 
During processing of the EMT the message is copied to an internal buffer, and the sending program is free 
to destroy its message on return from the EMT. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 0.104 

.WORD chnadr 

.VORD msgadr 

.tfORD msgsiz 

9S 
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where ehnadr is the address of a six byte field containing the name of the message channel (ASCII with 
trailing blanks if the name is less than six characters), msgadr is the address of the beginning of the message 
text, and mtgsiz is the message length in bytes. 



Error 
Code 



Meaning 



Job does not have MESSAGE privilege or system does not include 

message channel support. 

All message channels are busy. 

Maximum allowed number of messages already in message queues. 

The transmitted message is too long. The message is truncated to 

maximum allowed length. 

Maximum number of message requests pending. 



The system manager may alter parameters during TSX-Plus generation to alleviate these error conditions. 



Example 

.TITLE SNDM80 

.ENABL LC 
: DvBonitrattt uit of tht TSX-Plai ENT to qnout a ■•■■&!• to tho Intorprocost 
: ■•••«§• eoaaunleatlon fkcillty. 



BUBTT 
STAET: 

1$: 



01: 



N86BLI: 



NSGLEN: 
EltTBL: 



NOPIIT 
BSYEIi 

rULEU 

OHOH: 

TENEU 

NSGPIT 
CNLPIT 
DOHEOK 

CNLBUF: 
N8GBUF: 



.NO ALL 
■ 62 
.GTLIN 
NOV 
TSTB 
BNE 
SUB 

NOV 
.GTLIN 

NOV 

ENT 

BCC 

NOVB 

ASL 

.FEINT 

.EXIT 

CL&B 

.P&INT 

.P&INT 

.EXIT 

.NLIST 

.BYTE 

.VOiO 

.WOU) 

.WO&D 

.WO&D 

.VOU) 

.VOED 

.VOED 

.VO&O 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCII 

.EVEN 

.BLIB 

.BLIB 

.END 



EXIT.. PUNT.. GTLIN 

:ENT orror byto 
;G«t tht Hoii&gi to bo qatatd 
;Polnt to boglnning of boffor 
;Flnd ond of atiiago 



fNSGBUF.f NSGPIT 

fNSGBUF.ll 

(ID* 

1$ 

ff<NSGBUF«l>,ll 



;Dot«rmlno aotiago longth 
;aecottntlng for poit-lBcr»«nt 

Kl, NSGLEN :S«t ■•■•ago longth In ENT arg block 

iCNLBDF,«CNLPlT :6ot tho six eharactor ehannol naao 

fNSGBLI.IO :PolBt to ENT arg block to 

376 ;Sond ataaago on naaod channtl 

St :Branch if no trror 

•«E1IBTT,10 ;¥hich orrorT 

10 ;ConTtrt to word Indox 

BilTBL(EO) ;Dlapla7 tho appropriate aoaaago 

CNLBVF«6 :Nako ehannol naao ASCIZ 

iDONEOI ;InforB aaor aoaaago quouod 

fCNLBDF :on ehannol CNLBUF 



;ENT bloek: aond BOBBaga on nanod ehannol 
:AddroBa of ehannol naao 
;AddroBB of aoaaago 
;Char longth of aoaaago 
;Tablo of aond orror aoaaagoa 



;Error eodo 3 not naod 



BEX 

0.104 

CNLBUF 

NSGBUF 



NOPIIT 

BSYEU 

FULSU 

OHOH 

TENEU 

/TSNDNSG-F-No prirllogo or no aoaaago anpport./ 

/TSNDNS6-F-A11 aoaaago channola aro baay./ 

/TSNDNSG-F-Naxlaaa noabor of aoaaagoa hart boon ipioaod./ 

/TSNDNSG-F-Thla la a non-oxiatont orror./ 

/TSNDNSG-W-Noaaago waa too long, trnneatod./ 

/Noaaago to bo qaonod: / 

<16><12>/Channol Naao (alx eharaetora aax) : /<200> 

/Noaaago qaonod on ehannol /<200> 



80. 
80. 
STAET 



;FirBt 6 ehara to contain fllo naao 
:NoaBago bnffor. 
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6.3 Checking for pending messages 

The following EMT is used to receive a message from a named channel if a message is pending on the channel. 
If no message is pending, an error code (S) is returned, and the program is allowed to continue execution. 
The form of the EMT is: 



e;mt 



375 



with RO pointing to the following argument area: 

.BYTE 0,105 

. WORD chnadr 

. VORD msgadr 

,VORD megsiz 

where chnadr points to a field with a six character channel name, mtgadr points to the buffer in which the 
message is to be placed, and mtgaiz is the size of the message buffer (bytes). 

If a message is received, its length (bytes) is placed in RO on return from the EMT. If the message is longer 
than the message buffer [mtgtiz], only the first part of the message will be received. 



Error 
Code 



Meaning 



Job does not have MESSAGE privilege or system does not include 

message channel support. 

All message channels are busy. 

No message was queued on the named channel. 

Message was longer than the receiving buffer. 

Maximum number of message requests pending. 



Example 



.TITLE 
; De>onatrat«t 
; Interproctft 

.NO ALL 



EE&BYT 
START : 



U: 



2$: 
6$: 

NSGBLK: 



' 52 

.CTLIN 

NOV 

EMT 

BCC 

TSTB 

BNE 
.P&INT 

BE 

CMPB 

BEQ 
.PKINT 

BE 

.PEINT 

.PEINT 

.PEIKT 

.EXIT 

.BYTE 

.WORD 

.VOED 

.WOED 

.NLIST 



QETNSG 
Qtt of th* TSX-PluB ENT to chock for ponding aottaBoi in tho 
■oioftgo eosBunlcation facility. 
.EXIT.. PEINT.. GTLIN 

;EMT orror bjto 

;Got tho ehumol naao 

:Put ENT argiiBont block addrooi in EO 

;ENT to chock chumol for aoooago 

;ErrorT 

:No prlTllogo? 

;Bruich if dlfforont orror 



fCNLBUF.fCNLPET 

iMSGBLE.EO 

376 

6t 

«»EEEBYT 

II 

«NGPEIV 

9< 

•«EEEBTT.i4 

2$ 

fNONEEE 

«( 

iTENEEE 

iPNDNSG 

9N8GBUF 

O.IOE 

CNLBUF 

NSGBUF 

81. 

BEX 



iOnly two orroro potilblo 
:OTorflow Bifiiago bufforT 
iNo BOBoago 

; Print truncation warning 
;Print ■oaoago proaabla 
; Print actual Boaoago 

;6ETNSG ENT block 
;Chaiinal naao buff or addroaa 
:Buffor addroaa to rocoivo Boaaago 
;Buffor longth 
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CNLBUF : 
NSGBUF : 



CNLPIT 
NOMEU 
TINEU 

PNDNSG 
NOPIIV 



;Flrit 6 chart ar« 
:N«iiag« baffar 
ilntur* iSCIZ 



.BLIB 80. :Flrit 6 eh*r» ar« ch«nJi*l naa* 

.BLKB 80. 

.VOEO 

.NLIST BEX 

.ASCII /Chtnntl Nut (8 chut): /<200> 

.ASCIZ /TGETMSG-F-No attBHtas ptndlng In nuitd chaimal./ 

.ASCII /?GETMSG-W-Mt»9ag« tnu»e*t«d/<7> 

.ASCIZ /Mtiiag* pandlng In niacd qn«n* !■:/ 

.ASCIZ /TGETHSG-F-No prlTlltg* or no ■•■■ago topport./ 

.LIST BEX 

.END STAIT 



6.4 Waiting for a message 



The following EMT b used to suspend execution of a program until a message becomes available on a named 
channel. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 



.BYTE 
.WORD 
.WORD 
.WORD 



0.106 
chnadr 
msgadr 
msgsiz 



where chnadr points to a six byte field containing the channel name, mtgadr points to the buffer where the 

message is to be placed, and mtgaiz b the size of the message buflFer (bytes). 

The length of the received message (bytes) b placed in RO on return from the EMT. 



Error 
Code 



Meaning 



Job does not have MESSAGE privilege or system does not include 

message channel support. 

All message channels are busy. 

Message was longer than the receiving buffer. 

Maximum number of message requests pending. 



Example 



.TITLE YATNSG 

.ENABL LC 
Dtaonitr&tt TSX-Plui EKT to wait for a quouod ■••■ago froa th^ 
Int^rprocoi* ■•■■ag^ eoaaanleatlon facility. 

.NCALL .EXIT . .PilNT , .OTLIN 



EilBTT 


. 52 




;EMT orror byte 


8TUT: 


.6TLIN 


*CNLBUF,«CNLP1T 


;Got th« channel &•■• 




.PftINT 


fWAITNG 


■.Explain valtlng 




NOV 


fNSGBLK.lO 


:Pat ENT arguaant block addroa^ In 10 




ENT 


976 


:ENT to chock chanaol for ■•■•ag* 




BCC 


51 


:Chack for orror 




ISTB 


ffEUBYT 


;No prlTllogoT 




BNE 


U 


;Branch If dlfforont orror 




•PIIKT 


«NOPRIT 






BE 


SI 
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U: 


CNPB 
BHI 
.PRINT 
BR 


tiRRRRYT, 
2$ 

iNONRRR 
0$ 


#1 






; Error? 

;N«taaga truncatod 

;A11 ehannols buiy 


21: 


.PRINT 


iTRNERR 








;Print truncation warning 


El: 


.PRINT 
.PRINT 


«RCVNSG 
«NSGBUF 








; Print Bttaagt proaHblo 
: Print actual aoaaaga 


B$: 


.EXIT 












NSGBLI: 


.BTTE 
.VORD 
.WORD 
.VORO 


0,100 

CNLBUF 
NSGBUF 
81. 








;VATNSG ENT block 
; Channel naan buff or addroia 
;Buff«r addr<»i« to rocolTt ■•••ago 
;Buff«r length 


CNLBUF 


.BLIB 


80. 








: Channel naa<i fir at 6 ehara 


N86B7F 


.BLXB 
.WORD 
.NLIST 


80. 



BEX 








:NeaBage buffer 
;Ineure ASCIZ 


CNLPIT 


.ASCII 


/Channel 


Ntat 


(0 chars) 


/<200> 


WilTNG 


.ASCII 


/Valtlng 


for • 


■•■■agt 


. . ./<16><12> 




.ASCIZ 


/Go to anothor 


lint and 


•end BO soBothing./ 


NONRRi 


.ASCIZ 


/TITATMSG- 


-F-All 


Btttago 


ehannela are buay./ 


TRNERR 


.ASCIZ 


/TVATNSG-¥-N«t>ag« 


tnincattd./<7> 


RCVNSG 


.ASCIZ 


/Noiiagt 


rtetlTtd 


In namod qaaua it:/ 


NOPRIV 


.ASCIZ 


/TWATMSG-F-No 


prlTllogt 


or no Boe^agt aupport./ 




.LIST 


BEX 












.END 


START 











6.5 Scheduling a message completion routine 

The following EMT is used to schedule & completion routine to be entered when a message is received on a 
named channel. The form of the EMT is: 



EMT 



375 



with RO pointing to an argument block of the form: 



.BYTE 


1,106 


.WORD 


chnadr 


.VORD 


msgadr 


.VORD 


msgsiz 


.VORD 


cplrtn 



where chnadr points to a six byte field containing the message channel name, magadr is the address of the 
buffer where the message is to be placed, mtgtiz is the size of the message buffer (bytes), and cplrtn is the 
address of the completion routine to be entered when a message is received. 

On entry to the completion routine, RO contains the number of bytes in the message that was received and 
Rl contains the number of the job that sent the message. Another message completion routine may be 
scheduled from within the completion routine if desired. 

The .SPND and .RSUM system service calls may be used with this facility if the program reaches a point 
where it must suspend its execution until a message arrives. 



Error 
Code 



Meaning 



Job does not have MESSAGE privilege or system does not include 
message channel support. 

All message channels are busy 

Message was longer than the receiving buffer. 

Maximum number of message requests pending. 
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Example 



.TITLE NSGCPL 

.ENABL LC 
Dmonitrftt* attaagt coaplatlon routln* 
Do proceaalnf vhil* valtlng for a ■••■aga, 
than dlaplaj tha Haaaaga and rapaat. 

.MCALL .PlINT , .EXIT . .TTYOUT 





.GLOBL 


PETDEC 






.DSABL 


OBL 




Rt&RTT 


> 63 




ENT arror byta addraaa 


SPACE 


« 40 




ASCII apaea char 


BELL 


- 7 




ASCII ball char 


tEPTS 


. 60 




Ontar idla loop rapaat eountar 


WIDTH 


- S3. 




Seraan formatting vidth 


; Schadula Baaaaga coMplatlen loutlna 


ST AIT: 


NOV 


iNSGCFL.EO 


;Point to ENT arg block to 




ENT 


376 


: Schadula co^ilation roatina 




BCC 


31 


:Branch if 01 




NOVB 


•tR&RRYT.El 


;Gat arror coda 


11: 


ISL 


El 


sConrart to word indax 




.PIIHT 


SCHKRR(il) 


:Print appropriata arror aaaaaga 




.EXIT 




;quit 


: Idla 


procaaaj 


Lng loop vhlla waiting for eoaplatlon roatina 


31: 


NOV 


•IEPTS,E2 


; Qatar idla loop coontar 


3$: 


NOV 


f-l.&S 


slnnar idla loop coontar 




I8T 


NESSAG 


;An7 Baaaaga pandingT 




BEQ 


61 


:Do othar proeaaaing if not 




BNI 


4$ 


:Nag eoapl rtn orrorT 




CALL 


DSPNSG 


:No arror, dlaplay Baaaaga 




BE 


3$ 


;Contlnaa waiting for naxt 


41: 


NOV 


NESSAG, El 


:EacoTar arror coda 




BE 


11 


;6o print arror and dia 


6(: 


SOB 


ES,E$ 


;Innar idla loop 




SOB 


Ea.st 


iOatar idla loop 




• TTTOITT 


fBELL 


;Indleata actirlty 




BE 


2t 


;And rapaat forarar 


; Dlaplay tha 


racalvad Baaaaga 




D8PNSG: 


NOV 


ES,-(SP) 






.PEINT 


•C&LF 


;ForBat diaplay 




NOV 


NSGLEN,12 


:Gat langth eoant 




NOV 


Ea.KO 


; Again for diaplay 




CALL 


PETDEC 


;Show Baaaaga alia 




.PEINT 


ffHSGF&N 


:"byta Baaaaga rac'd froB Job #' 




NOV 


JOBKUN.EO 


:Gat aandlng Job noBbar 




CALL 


PETDEC 


; Diaplay Job naBbar 




NOV 


fNSGADE.El 


;Gat pointar to Baaaaga 




ADD 


E1.K3 


;SaTa pointar to Baaaaga and 


1$: 


NOV 


#VIDTK,E4 


;Diaplay-width coontar 




.PEINT 


•LEFT 


:ForBat diaplay 


a$: 


NOVB 


(El)^.EO 


;6at naxt charactar 




CNPB 


EO.fSPACE 


:PrintablaT 




B6E 


3$ 


{Branch if ao 




.ITTOOT #'• 


;Narlc control charactar 




DEC 


E4 


:Snb 1 froB width 




NOVB 


-1(11) .EC 


;EacoTar charactar 




ADD 


f't.EO 


:ConTart to opparcaaa char 


3$: 


.IITOUT 


; Diaplay char 




CNP 


E1.E2 


;End of diaplay? 




BHI8 


41 


;Braneh if ao 




SOB 


E4.3I 


;Continaa onlaaa naad to wrap 




.PEINT 


tEIGHT 


; Format diaplay 




BE 


11 


sNaxt Una 


4$: 


.PEINT 


fEIGHT 


;ForBat diaplay 




CLE 


NESSAG 


;Say wa ara dona with thia ono 




NOV 


(SP)+.13 






EETUUI 
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Completion routln* to bt anttrod whtn ■•■■ago rocuivod 



CPLITN : 



NBS8AG 
II 

lO.NSGLEN 

ll.JOBNUN 

«1,NESSAG 

«NSGCPL,10 

37B 

3$ 

««ER&BTT.KESSAG 

«100000,NESSAG 



T8T 

BNK 

NOV 

NOV 

NOV 
1$: NOV 

ENT 

BCC 

NOVB 

BIS 

21 : &ETDLN 
; EMT arg blocks and word buffora 



NSGCPL: 



JOBNITM;: 
N8GLEN:: 
NE8SAG:; 
SCHEU: 



.BYTE 
.WORD 
.VORD 
.WORD 
.VORD 
.WORD 
.VORD 
.VORD 
.VORD 
.VORD 
.VORD 
.VORD 
.VORD 
.VORD 



1,106 

CHANAN 

MSGADR 

NSGEND-NSGADl 

CPLRTN 







NOPRIV 

NOFREE 

UNUSED 

UNUSED 

TOOLNG 

NOMRB 



;Don« with laat ■•■■agtT 

;Branch (and loa« this ono) If not 

;SaTa ■•■■ago longth 

;SaTa ■•nding Job nunbor 

;Flag ■•■■aga rac^lrod 

;Point to ENT arg block to 

;I*Bch^dul^ ■y^^lf 

;Branch if OE 

;Elaa ■■to arror eod« 

:And flag it aa arrosr 



rtn 



ENT arg block - aag coapl 
Polntar to channal nasa 
Addroa^ of ■•■■ago buffer 
Slio of ■•■■ago buffer 
Address of coapletion routine 
Cell for i of ■•■■age aender 
Cell for roc«lT«d ■•■■aga langth 
Cell for ■ag rcTd signal 
Nag coiq>l rtn sehod orror tabla 
1 No fro* ■•■•ag* channels 
a Nax ■••■agaa alraady quau^d 
S No ■•■•aga quau^d on channal 

4 Na^^aga OTarflowod buffer 

5 Nax ■••■agaa raqu^^ta pending 



NeaiagoB and byte buffera 
.NLIST BEX 



CHANAN 

NOPRIV 

NOFREE 

UNUSED 

TOOLNG 

NONRB: 

NSGFRN 

CtLF: 

LEFT: 

EIGHT: 

NSGADR 

MSGEND 



.ASCII /CHANEL/ :Na>a of vatched ■ea^age channel 

.ASCIZ /No privilege or no ■esaaga Bapport./ 

.ASCIZ /All ■•aaaga chaimela are buay./ 

.ASCIZ /NSGCPL should noT^r g^n^rate thla arror./ 

.ASCIZ /Neaaage waa longer than ■aaaaga buffer./ 

.ASCIZ /Naxl^uK nu^b^r of ■••■age requasta panding./ 

.ASCII / byt^ ■•■•age raeelTod fro^ Job nnaber /<200> 

.BYTE 16,12.200 

.ASCII <lB><12>/"-/<76><200> 

.ASCII <74>/— /<200> 

.BLIB 200. :Neeaage buffer 

.LIST BEX 

.EVEN 

.END START 
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Chapter 7 

Programming for CL and Special 
Device Handlers 



Several device handlers are uniquely integrated into the TSX-Plus environment. The communication line 
handler (CL), the logical subset disk handler (LD), the terminal line handler (TT), and the single line 
editor (SL) are provided as integrated system features and do not require device declarations (DEVDEF). 
The professional interface handler (PI) is provided with PRO/TSX-Plus and when used is defined as a 
shared run-time system and not as a device handler. The TSX-Plus virtual memory handler (VM) utilizes 
knowledge of the TSX-Plus environment to determine the usable memory space available. VM is the only 
special TSX-Plus device handler which requires a device declaration (DEVDEF) in order to be used. 

7.1 Communication line handler (CL) 

The CL handler allows Input/Output operations to be performed to serial communication lines connected 
to any type of interface controller which may be used for terminal lines. With the CL handler it is possible 
to have some lines on a multiplexer used as TSX-Plus time-sharing lines, and other lines on the same 
multiplexer used to drive I/O devices such as printers, plotters, and modems. It is also possible to use a line 
as A, time-sharing line some of the time and as a communications line at other times. Some of the important 
features of the CL handler are summarized below: 

i • jjp I p. Ift.^communication lines may be controlled through the CL handler. The first 8 CL units are 
V named CLO through CL7, the second set of 8 units are named ClO through C17. The lines may be 

connected to any type of communication controller that is supported by TSX-Plus and may share the 

same multiplexer controllers as TSX-Plus time-sharing lines. 

• Lines may be dedicated as communication lines or may be switched between time-sharing lines and 
communication lines. 

• Internal queueing is used within the handler to allow concurrent input/output operations to be per- 
formed on all of the lines. 

• The CL handler allows both input (read) and output (write) operations. Full duplex (simultaneous) 
read and write operations may take place on each line. 

• The communication lines may be used with the TSX-Plus spooling system to allow spooled output to 
devices on communication lines. 

• The CL handier responds to XON/XOFF (GTRL-Q/CTRL-S) control characters to stop and start its 
transmission and will generate XON/XOFF characters to control the speed of a device transmitting 
to a CL line. 
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• A binary mode is available for CL lines to allow full 8-bit, transparent I/O to devices. 

• Modem control is supported. Ring and carrier detect signals may be monitored and data terminal 
ready (DTR) can be controlled by a program or SET command. 

• The CL handler is implemented as a system virtual overlay, minimizing the amount of code and data 
that b required in the unmapped portion of the system. 

• The CL handler can be used as a replacement for the LS, XL, and XC handlers (the XL and XC 
handlers are used with the RT-11 VTCOM program). 

• A terminal can be crost connected to a CL line by use of the SET HOST command so that characters 
typed at the terminal are sent directly out the CL line and characters received on the CL line are 
displayed at the terminal. 

Once a system has been generated with communication lines, the lines may be accessed as normal devices 
using the names CLO, CLl, ClO, C17, etc. K the CL handler is used to drive the system printer, it is 
convenient to use an assign command to assign the logical name LP to the corresponding CL device. 

The device name CL is functionally equivalent to CLO. CI Lb equivalent to ClO. Attempts to use a CL unit 
which is not currently associated with a line will return an error status just as if the CL device was not 
recognised by the system. 

CL units specified using the CLDEF macro in TSGEN are initially connected to dedicated CL lines. Note 
that although these lines are dedicated for use by CL, the CL units which are initially assigned to these lines 
may be reassigned to other lines. The unallocated CL units declared by use of the CLXTRA parameter in 
TSGEN are initially not associated with any line. The SET CLn LINE=n and SET HOST/PORT=CLn 
keyboard command or the system service call (EMT) can be used to assign any CL unit to any free time- 
sharing line or free dedicated CL line. Thus it is possible to use a line as a TSX-Plus time-sharing line 
during certain portions of the day and then assign a CL unit to the line and use it to drive a modem or other 
device at other times. Dedicated CL lines use less memory space than time-sharing lines but may only be 
accessed as CL units. See the TSX-Plua Reference Manual for a full description of the SET CL and SET 
HOST command. TERMINAL privilege is required to use these SET commands. 

Subsequent sections in this manual discuss special programming techniques for CL units. 

7.1.1 VTCOM/TRANSF support and CL handler 

The RT-11 VTCOM/TRANSF file transfer programs may be used to communicate and transfer files between 
RT-11 and/or TSX-Plus systems. 

When VTCOM is used to communicate with another system, the system where the user is located and 
running VTCOM is known as the heal system whereas the remote system to which communication is taking 
place is known as the host system. TSX-Plus may be used either as the local system, the host system, or 
both. 

The user at the local system runs the VTCOM program to initiate communication with the host system. 
The VTCOM program uses the CL handler to connect to a communications line. The CL handler must be 
associated with a serial port of any type which is valid for terminal lines that is connected either directly or 
through a modem to the host system. 

When TSX-Plus b used as the local system, the lOABT sysgen parameter must be set to 1 to enable handler 
abort entry code. 

If the CL handler is used with the VTCOM program, it b necessary to assign the logical name XL (or XC 
if on the Professional) to the CL (or Cl) unit controlling the communications line. It b abo a good idea 
to allocate the device so that conflicts with other users will not occur. The NOLFOUT option should be 
specified for a CL line used with VTCOM. For example, the following commands would be appropriate to 
direct VTCOM to use line CLO: 
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SET CLO NOLFOUT 
ASSIGN CLO XL (or XC) 
ALLOCATE XL (or XC) 

^cv^dT^^."^^''';' "''^" ^^' ^""'^ '^'^'"'' '^^ *^°""«<^ti«'^ froni the local system may be made through any 
i^" .ix^o ^'ILf *" """ ^^* ^""'^ 'y''*""- ^^'^^ "'^** ^^^ fil« transfers between a TSX-Plus system 

and a VMS system, VMS must be the host system (there is currently only a TRANSF program for VMS 
but no VTCOM). ' 

7.1.2 Terminal/ Communication line cross connection 

It is possible to cross connect a time-sharing line with a CL (communication line) unit in such a fashion that 
all chaxacters received from the time-sharing line are transmitted directly to the CL unit and all characters 

ir^nf 1 nel on. TSY^Vr ''T""f"t ^^"f^ '" '^' time-sharing Une. This is useful to allow a time- 
sharmg hne on one TSX-Plus system to be used as a terminal on another system connected through a CL 

^htre?^''^?^ i' ^^"^^^" *Vtu' ^^^^^ '° communicate through a CL line but has the advantage that 
there is much less overhead. The cross connection is made at a low level within TSX-Plus and characters 
do not have to be passed to a running application program. Of course the internal cross-connectionTature 
does not provide the file transfer capabilities of VTCOM. Other disadvantages are that a cross-connected 
line cannot be switched to a sub-process and Process Windowing is temporarily disabled. 
The keyboard command used to establish a cross connection has the form: 

SET HOST/PORT=ddn 

r^^Tif '''*• '" ^^^ """"^^ °^ " *^^ °' ^^ ^^""'^^ '° ^**^"^ y'^*^' *«™i^»» '^ to be cross connected. For example 
Z '^lZ:Zl^r^^^ "' ^'^^^ ' -''' '-''^ ^^^ ' ^' '^'^ '-' -' ^^- — -/ect 

SET CLl LINE=4 , SPEED=9600 
SET H0ST/P0RT=CL1 

TERMINAL privUege is required to use the SET HOST command. Once the cross connection is established 
characters typed at your terminal are transmitted to the CL line. onnection is established, 

!onntlio?s^'^'"' ^'"'^' ^'^"'"" ^''*"°' ^°' '"°'' information on the SET HOST command and cross- 

7.1.3 Redirecting CL and time-sharing lines 

A system service call (EMT) is available to allow n program to assign a CL unit to a particular Une This 
EMT IS equivalent to the SET CLn LINE=n command. The form of the EMT is: P""'''''" ''^*- "^^^ 

EMT 375 

with RO pointing to an argument block of the following form: 

•BYTE 0,155 
.WORD cl-unit 
.WORD line -number 

tSLldcl Hn?' ^\r^ ''T^/V- ''^^ '•"5-""'"^^'', '' '^' '^^"^^^^ °f ^ TSX-Plus time-sharing line or 

TERMNA^ i '^""f"^ ^'"' "^'"^"' '' ° ^'^"^°^' '^' CL unit is disassociated from any line 

1J1.KM1NAL privilege is required to use this EMT. ^ 

If an enor is detected, the C-flag is set on return and the following error codes are returned: 
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Code I Meaning 



User issuing the EMT does not have TERMINAL privilege 

An invalid CL unit number was specified 

An invalid line number was specified 

The specified line is already assigned to a CL unit 

A time-sharing user is logged onto the specified line 

The specified CL unit is currently busy 



The following example commands illustrate how CL unit 1 can be assigned to time-sh^ing line 2 The 
logical name LP is then assigned to CLl so that the PRINT command will d^ect output through CLl. CLl 
can be declared to be a spooled device in TSGEN: 

SET CLl LINE=2 
ASSIGN CLl LP 

The SHOW CL and SHOW TERMINALS keyboard commands can be used to display information about 
wh ch CL units are associated with which lines. The SHOW CL command also mdicates if a CL umt is 
Tpooled and lists the options which are set for the unit. See the TSX-Plue Reference Manual for information 
concerning the SHOW command. 

7.1.4 CL I/O operations 

The READ/ READC/.READW and . WRITE/. WRITC/. WRIT W EMTs may be used to perform standard 

read/write operations to the CL lines. The CL handler allows full duplex input/output operation, which 

means that read and write operations may be simultaneously active on a CL line. 

When a .READ(C/W] EMT is used to read from a CL line, the operation is complete when the requested 

number of words have been accepted or a CTRL-Z character is received. 

The input character silo is used to store characters received from the Une. ThU buffer prevents characters 

from being lost during the interval when one read EMT is completed and another is issued to the CL handler. 

The CL handler responds to received XON (CTRL-Q) and XOFF (CTRL-S) characters, starting and 

suspending transmission to synchronize its character flow with the device connected to the Ime. 



7.1.5 CL control character processing 

Processing of certain control characters through CL units depends on the individual character, the settings 
of the CL unit, and the particular operation in progress. 

The following table illustrates the handling of special input characters to a CL unit. Control characters not 
listed are treated as normal characters on input. 



Char 



NUL 



LF 



CR 



XON 



XOFF 



Octal Value | Input Handling 



Discarded unless in binary input mode (BININ). 



12 



15 



21 



23 



Discarded unless in LFIN mode (always input by .SPFUN 2087" 



Always input. Also terminates read for .SPFUN 260. 



Re-enables transmission to CL unit, except in BININ mode when 
it is input as a normal character. 



32 



Halts transmission to CL unit, except in BININ mode when it is 
input as a normal character. 



Sets end of file flag and terminates read (except for .SPFUN 203 
by which "Z is treated as a normal character). 
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The following table illustrates the handling of special output characters to a CL unit. In NOCTRL mode 
control characters not listed are not sent. In BINOUT mode, all special control character output processing 
is bypMsed. In addition, in BINOUT mode automatic XOFF transmission when the input silo becomes full 
is disabled. 



Char 



NUL 



TAB 



LF 



FF 



CR 



Octal Value 







11 



12 



14 



15 



Output Handling 



Never sent except in BINOUT mode. 



Expanded to spaces in NOTAB mode. In TAB mode and width 
not set to 0, TAB is discarded if it would exceed the set width, just 
as normal characters are. 



Discarded in NOLFOUT mode if preceding character was a carriage 
return. 



In NOFORM mode, FF is expanded to enough line feeds to advance 
to the top of the next page. 



Discarded in NOCR mode. 



7.1.6 CL .SPFUN operations 

The following special function codes (.SPFUN EMTs) are recognized by the CL handler. The special 
functions apply to the specific CL unit to which the channel was opened. 



Code 


Function 


201 


Clear XOFF status 


202 


Control break transmission 


208 


Read with byte count 


204 


Get handler status 


205 


Terminate I/O 


206 


Raise or drop DTR signal 


250 


Set option flags 


251 


Clear option flags 


252 


Set page length 


25S 


Set skip lines 


254 


Set page width 


255 


Get modem status 


256 


Set line speed 


257 


Abort pending I/O 


260 


Read a line of input 


261 


Get number of input characters pending 


262 


Get number of output characters pending 


268 


Write with byte count 


264 


Set ENDPAGE and ENDSTRING parameters 


265 


Reset CL unit 


266 


Get current characteristics of a CL unit 



Function 201 Clear handler 

This function clears the internal handler flag that says an XOFF (CTRL-S) character has been received 
and transmits an XON (CTRL-Q) to the CL device. 

FunctJion 202 Control break transmission 

This function starts or stops the transmission of a break signal. The word count specified with the 
•SPFUN controls whether transmission of a break signal is started or stopped. If the word count is 
non-zero, break transmission is started; break transmission continues until another .SPFUN is done 
with function code 202 and a word count of zero. 
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Function 203 Read with byte count . • * j rp, • 

This function performB a read operation but the word count value specifies a byte count instead, ihis 
function does not complete until at leaat one byte is read. However, if a byte count greater than one 
is specified bytes are moved from the input silo buffer until either the specified byte count is satisfied 
or the input silo buffer is emptied. If fewer than the requested number of bytes are available, the 
remainder of the buffer is filled with nulls. The CTRL-Z character does not signal end of file for this 
type of read— CTRL-Z is read as an ordinary character. 

Function 204 Get handler status 

A status code is stored into the first word of the buffer specified with thb function. The meaning of 
the flag bits is as specified below: 



If 



Bit 0=1 
Bit 1=1 
Bit 2=1 

Bit S=l 
Bit 4=1 



Then 



XOFF has been sent to stop transmission 
XOFF has been received from the remote device 
Carrier has been detected (same as bit 5) 
(This bit does not indicate CTS status) 
Carrier has been detected (same as bit 2) 
Ring signal is present 



Function 205 Terminate I/O to the line 

This function turns off a communication line. The input silo buffer is emptied (its contents are 
discarded) and a flag is set causing any other characters received from the line to be discarded. Data 
Terminal Ready (DTR) status is dropped. The line will be turned on again whenever another I/O 
operation is performed to it. 

Function 206 Raise or drop DTR signal 

Thb function can be used to raise or drop the Data Terminal Ready (DTR) signal for a line connected 
to a CL unit. If the word count value specified with the .SPFUN EMT is non-zero, the DTR signal is 
rabed; if the word count value b (zero) the DTR signal b dropped. 

Functions 250 and 251 Control option flags 

These special functions are used to set and clear handler option flags. Function 250 sets the specified 
flag bits (via a BIS instruction), function 251 clears the specified flag bits (via a BIC instruction). The 
flag bits which are set (1) correspond to handler SET options. If the option flag b cleared (0), thb 
corresponds to the NOoption setting. The bit positions of the options are shown in the following table. 
The option flags are contained in a one word buffer for the .SPFUN. For a detailed description of the 
SET commands, see the TSX-Plut Reference Manual. 



Bit Mask 




1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 



000001 
000002 
000004 
000010 
000020 
000040 
000100 
000200 
000400 
001000 
002000 
004000 



Option 



FORM 

TAB 

LC 

LFOUT 

LFIN 

FORMO 

BINOUT 

BININ 

CR 

CTRL 

DTR 

EIGHTBIT 



Function summary 



Send form feed characters 

Send tab characters 

Send lower case characters 

Send line feed characters 

Accept line feed characters 

Send form feed on block write 

Send binary output characters 

Accept binary input characters 

Send carriage return characters 

Send control characters 

Rabe Data Terminal Ready (DTR) 

Accept and send 8 bit characters 



Function 252 Set page length 

Thb function performs the operation of the SET CL LENGTH=n command. The .SPFUN must have 
a one word buffer containing the number of lines per page. 
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Function 253 Set skip lines 

This function performs the operation of the SET CL SKIP=n command. The .SPFUN must have a 
one word buffer contammg the number of lines to skip at the bottom of the page. 

Function 254 Set page width 

This function performs the operation of the SET CL WIDTH=n command. The .SPFUN must have 
a one word buffer containing the line width. 

Function 255 Get modem status 

This function is used to check on the status of a modem connected to a CL line. The modem status 



Bit 



Meaning when set 



Ring indication 

Carrier is detected 

Data Terminal Ready is asserted 



Function 256 Set Ime speed, character length and parity control 

I his function is used to set the transmit/receive speed for a CL line THi« 9PFTTTSI • 

word buffer containing a value which has the followLg form On bin 1^): ^ ^^ ''^""" ' "'^^ 

OPLxSSSS 

..selected; if bit 7 1. 1 odd p„ity i. .elected' Not. th!t if oi "t: fp" d'taL i^ p"cLT"wftn 
other bits lero, 8 bit chiracters with no parity are selected. >P«lfied, with all 

uiVr^'lXXrDz'r'rtll 'i":r p"7''' '°,''"''""° "•»"""'" ""' -P""" programmable 

not supportld t "-. iirra^eTotttk^rtrdi^grrEC^^^^^^^ ^tU ",'1?/^°' ''^"^ " 
works with most DEC DZll controller.1 Th. nmi J . controUer (although it actually 

72no- .^A ti,. niiu7, J oo"'""*")- The DHll does not support baud rates of 2000 J600 or 

7200, and the DHVll does not support baud rates of S600 or 7200. ' 

Function 257 Abort pending I/O 

Abort all pending read and write operation, iwued by the job executing the .SPFUN on the CL unit 
Function 260 Read a line of input 

This special function reads a line of input terminated by a carriage return cl.»r»^t., Tl, j 

iftr^ifrngtLtiz • ir '- ' ^"~ " ' '^^' co'- TLt^t'- iir:;!-' 

• The buffer is filled before a carriage return is received. 

• A CTRL-Z is received. 

Function 261 DetemJue number of input characters pending 

fr:;rcL ri^rit:dtitrrheX^5«:n^^^^ 

input prior to issuing a read (.REAdH SPF^) o» tt chi^T.l "S no T '^ "" '" ^'"^"^ 
attempts to read from the chainel wiU not complet.'un"iI the w^^dl byte) ct"nTL7umi!ed'lf '' 
do not wish to have a read request pending until the word (or byte) count ii fulflUeS^ fi^S H ; ^"^ 
the number of characters pending in the input buffer. If the e are nine do nofLsufthV^e^ ™"" 
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which have not yet been transmitted. 

Function 26S Write with byte count .Karactera to a CL line with the number of characters 

This special function is used to write a block ^.^ ^^^'^'^^ f " ^° ' ^J: ^WRITE EMT. ThU is useful in 
specified by a byte count rather '\^^'^l ^^^ ^l^^^l.^:^ be used to pad 

parameter (which is normally used to specify a word count). 

^:z ..in. (ENDSTRiNG) which wmb. ;;pp»jtr "tr w^M\ri^^^^^ 

address must point to a word aligned storage area ol wmcn 'i'^e Jirs^ , . -nnend 

form-feed characters. The second and subsequent words contain the strmg m ASCIZ form to append 
to the end; any characters beyond the first seven are ignored. 

"^-Th^ spfciS'funa^' ^el'^h'^^Utus of . CL unit by performing the following operation,: 

1. Empty the input silo of received characters. 

2. Empty the output ring buffer of transmitted characters. 
S. Stop sending a break if one is currently being sent. 

4. Clear XOFF (CTRL-S) received flag. 

5. Send an XON if we have previously sent an XOFF. 

6. Clear end-of-file status and reset line and column numbers. 

^1h- ^ciS^cLf rT^^^^^^^^ information about the CL unit. The buffer address must start 

on an even boundary and must be at least 12 words long. The values returned are: 



Offset 




Contents 



Handler status word (same as for .SPFUN code 204) 

CL options flags (same as for .SPFUN codes 250 and251) 

Internal status word (see bit description below) 

Page length 

Number of skip lines 

Page width 

CL unit number (CI units are 10-17 octal) (low byte) 

Line number in use as CL unit (high byte) 

Number of end of file form feeds 

ASCIZ string to send at end of file (can be up to 7 bytes plus one 

null) 



The following bits are defined in the internal status word: 



Mask 1 Meaning 



10 

40 

200 

4000 



Carriage return was the last character transmitted 

Next read will receive end of file 

Break being transmitted 

DTR has been asserted (explicitly by SET CLn DTR or setting 

the option flag, or implicitly by a READ or WRITE request) 
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Other bits are undefined and may vary. 

Example 

The following example program demonstrates use of some CL programming techniques which might 
be used to simulate a virtual terminal through a CL line. 

.TITLE CLCOMN 

"Slmpls" CL conunicatlont progria 

.DSABL GBL 

.GLOBL PIT&BO.PETDEC 

.NCALL . LOOKUP,. SPFUN,. CLOSE 

.HCALL .IIYOUT.. PRINT 

.NCALL .HEUL.. SEE!,. EXIT 



TIUSE 


- 1 


CMDCHl 


- 20 ;et] 


JSW 


" 44 


TTSPC^ 


t - 10000 


TTLC$ 


> 40000 


FREBYT 


- 62 


CLRBYT 


- 203 


CLOFF 


- 206 


CLCOP 


- 261 


CLIPND 


- 261 


CLWBYT 


- 263 


CLEST 


. 266 



;Lint number to attach CL unit to 
;Exlt conand characttr 

;Job Status Word addrtit 
:Tarmlnal apaeial Boda bit (SINGLE) 
;Enabla lovar east inpnt bit 
:ENT arror bTta addraae 

8PFVN coda to raad CL with byta count 

SPFUN coda to turn CL unit olf 

SPFUN coda to claar CL flaga 

SPFim coda to gat • ehara panding CL input 

SPFUK coda to vrita CL with byta count 

SPFUK coda to raaat CL unit 



CLCHAN 



;I0 channal to uaa to uecass CLn 



; First tvo routinas handla thair own fatal arirors 



{ITAET: 



CALL 
CALL 



ITSET 
CLGET 



;Sat up tarminal charaetaristics 
;Get and initialiia CL Una 



FroB hara on, arrors ara handlad by Bain linn coda 

CALL TTINPC ;Quaua tarainal input co^>lation routina 

BCC II ;Continua if OE 

.PlINT ffBiDQUE :BlBa say what 'a wrong 

Bl 9$ ;And abort 



;; Start Bain loop — 
j[$: TST DONE 
BNE 91 



:Did tarBinal gira axit eoBsand chart 
;Bxlt on coBBand 



CALL 
BCC 



CLIO 
II 



:SarTlca any panding CL input or output 
;Continua if no arror 



;; ana h 
»|: 


am xeop 
CALL 


CLFKEE : Claar out CL lina and closa unit 




.PilHT 


«OFF 




.EXIT 




" 


.NLI8T 


BEX 


OFF: 


.ASCIZ 


/<Bxit>/ 


liADQUB: 


.ASCIZ 
.EVEN 


/Error qnaualng tarBinal input routina/<7> 




.LIST 


BEX 




.SBTTL 


TT8ET ~ Sat tanainal slngla, Ic 



^[TSET: .SBIl ; Inhibit Bonitor ENT arror handling 

NOV iSINGLE.lO ;Point to ENT arg block to 

ENT 376 :8at singla character actiTation 

BCS 71 ; Abort en ENT arror 



no 
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.HE£& 





BIS 




lEIU&N 


Tl: 


.KEU 




.PRINT 




.EXIT 


' 


.NLIST 


SINGLE: 


.BYTE 




.VOEO 




.VOED 


HOTTSX: 


.ASCIZ 




.EVEN 




.LIST 



;ltturn trror control to Bonitor 
f<TTLCDiITSPC|>,t«JSV ;Enabl« ■Inflo/le 



;Etturn trror control to aonltor 
iNOTTSX :ENT orror, Wkj bt ET-ll 



BEX 

0,152 :EMT arg block to tnablo 

'S :Slnglo charaetor Input 

;Dnuiad 

/Inralid ENT orror - cannot continnt/<7> 

BEX 



.SBTTL CLGET ~ find and Inltlallit CL lino 



CLGET: 



2$: 



S(: 



CALL 


ALCCL 


BCC 


2« 


.FEINT 


tCNTALC 


.EXIT 




CALL 


ATTCL 


BCC 


39 


.PIINT 


tNOCLS 


CALL 


ABO&Tl 


.EXIT 





CALL 



CLINI 



;Tr7 to allocata a CL unit 
;Contlnno if wo own a CL nnlt 
;Sa7 vo cannot got a CL unit 
;And abort 

:Tr7 to attach CL unit to lino 
;Contlntto If 01 
;8a7 can't connect 
;loloaio allocation 
;And abort 

:Tr7 to inltlallso tha CL lino 
iRandloa Ita ovn orrora 



.PRINT #CONECT ; Connecting 

NOV CLDET.IO :Cot CL unit 

CALL PITE60 ;and dliplay It 

.PIINT fTOLINl :to lino nnmbor 

NOV LINNDN.IO :6ot lino numbor 

CALL PETDEC ;and display It 

.PRINT tCRLF 
RETURN 



.NLIST BEX 



CNTALC 

CONECT 

TOLINE 

CRLF: 

N0CL8: 



.ASCIZ 

.ASCII 

.ASCII 

.ASCIZ 

.ASCIZ 

.EVEN 

.LIST BEX 



/Vnablo to allocato any CL Qnit/<7> 

/Connecting /<200> 

/ to lino number /<200> 

// 

/Unable to attach CL nnlt to a llne/<7> 



.SBTTL ALCCL ~ allocate a CL unit 



ALCCL: NOV «ALCENT.RO ;Polnt to ENT arg block to 

ENT 376 ; Allocate a CL unit 

NOV lO.CLOVN :ReBoaber who owne the CL unit 

BCC 91 : Normal return If allocation 01 



It: 



NOVB tiERRBTT.RO :See which error occurred 

CNPB RO.fi : Already allocated to another JobT 

BEQ 1$ :Tr7 next If ao 

CNPB R0,t4 :In nee by another JobT 

BNE SI :If any ether error, return with error 

NOV CLDEV.RO :Get current CL unit name 

CALL PRTR60 :And dlaplay It 

.PRINT iXTLDBT 
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IDt: 



NOV 

CALL 

.PEIKT 

INC 

INC 

Bi 

SEC 

lETU&N 



CLO¥N,10 :G*t Job nimbar of line using CL 

PITDEC :ind display it 

iCUF 

CLDEV ;Try noxt unit nuabor 

CLONIT ;and r«»bor which on* 

ALCCL ;And try to allocato it 

;Sat raturn arror flag 



.NLIST BEX 

ALCEMT: .BYTE C.1B6 ;EMT arg block to 

.WORD CLDEV :Allocata a CL unit 

CLOmJ: .WOED :Ovnar of tha CL unit 

XTLDBY: .ASCII / in uaa by Job /<aOO> 

.EVEN 

.LIST BEX 

.SBTTL ATTCL — attach CL unit to a IT lina 



JITTCL: MOV #GEICL.10 ; Point to BMT arg block to 

™T 876 ; Attach a CL unit to a T8 Una 
LETDIN 

.NLIST BEX 

(iETCL: .BYTE 0.1B8 ;EMT arg block to connoct CL to a Una 

CLITNIT: .VORO :CL unit nuabar 

LINNUN: .WORD TTDSE ;TT Una nuabar 

.LIST BEX 

.SBTTL CLINI — opan CL unit and Inlt it 



CLINI : 



II: 



21: 



.L00ID7 

BCC 

.PRINT 

CALL 

.EXIT 

•SPFUN 

BCS 

.SPFUN 

BCC 

.PRINT 

CALL 

.EXIT 



#AREA,#CLCHAN,#CLDBV jTry to opan CL channal 
II sContlnua If 01 
*BADLIP 

AB0RT2 ;Dliaociata and daallocata 
:And abort 

#AREA,iCLCHAN.#CLRSI.#CL0BOF,#0,#0 ; Flush CL 
21 ; Abort on arror 

#AREA.#CLCHAN,#CLCDP,iCLNFLG.#0,#0 ;Claar flags 

SI ;Contlnua if 01 

fCLIOEl 

CLFRSB sPurga channal, dlssoclata and daallocata 



91: 



RETURN 



CILDEV : 
CLNFLG 
BADLIP 
CLIOER 



.NLIST 

.RAD60 

.WORD 

.ASCIZ 

.ASCII 

.EVEN 

.LIST 



BEX 

/CLOFILNAMDAT/ ;CL darlca and duaay flla spae 

10 ;no(LFOUT) 

/Error opanlng CL nnlt/<7> 

"CL I/O arror''<r> 



BEX 



.SBTTL CLFREE ~ closa and daallocata CL unit 



; Flush tha channal and Ignora furthar input froa it 
CLFREE: .SPFUN #AREA.iCLCHAN.#CLOFF.iCLOBUF.#l.#l jium off CL 
.CLOSE fCLCHAN :Claar channal 

: leleasa tha taralnal froa tha CL lina 

AB0RT2: CLR LINNUM jClaar taralnal assigna.nt 

MOV iGETCL.RO jPolnt to EMT arg block to 
™^ S'^fi ;Dissoeiata CL unit fron Una 
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; D«allocatt th« CL \mit 

ABOIIl: MOVB tl.ALCBHT ;Changt illocat* to DEalloc»tt 
MOV iALCEXT.lO ;Polnt *• EMT arg block to 
ENT S7B ;Do*lloc»t» tht dtTlco 
lETUUI 

.SBTTL ITINP -- accopt and handlt taralnal Input 



TTINP; 



II: 



21: 
ITINPC ; 



CMP 10,#CMDCH1 ;!• It tho oxlt eonund eharT 

BNB ll ;Continu« 11 not 

INC DONE ;Say wo ahould quit 

lETUlN :ind oxlt without roquouolng 

MOVB 10.«TTIPTI :SaTO char to itnd to CL 

INC TTIPTI ;And point to ntxt poaltlon 

CMP TTIPTI. iCLOBOT) ;TiBO to wrapT 

BLO 31 ;Br 11 not ^ ^ ^, 

MOV #CLOBU?, TTIPTI :Wrap to boglnnlnf ol bulltr 

.TTTOUT ;Ditplay on TT (•• Muat ocho) 

MOV fQTTINC.EO :Point to BMT arg block to 

EN^ 87B ;toqutu« toralnal Inp co«p routlno 

lETDlN 



.NLIST 

DONS: .VO&D 

QTTINC: .BYTE 

.WO&D 

.LIST 



BEX 



1.133 

TTINP 

BEX 



Exit Hag (not — > oxlt) 

EMT arg block to quouo TT 

Input complttlon routine 



.SBTTL CLIO ■■- road and writo ponding CL I/O 



; Tranialt tormlnal Input out through CL lino 

CLIO: CMP TTOPTH. TTIPTI ;Ii thoro any nn char to aondT 

BEQ 11 ;Br 11 not 

.8PFDN iAaEX.iCLCHAN.iCLWBYT.TTOPTll.fl.tl ;Wrlto 1 byto 

BCS 91 ;lotnrn with orrort 

INC TTOPTl ;Polnt to noxt output char poaltlon 

CMP TTOPTE.tCLOBND ;Tl»o to wrap to boglnnlngT 

BLO 1$ ;Br 11 not 

MOV fCLOBUF, TTOPTl :¥rap to beginning ol bull or 



1(: 



Boo 11 any charactora aro coming In Irom tho CL lino 



.8PFUN 

BCS 

NOV 

CLC 

BEq 

.8PFUN 

BCS 

NOV 

NOV 

ENT 



•Am.#CLCHAN.iCLfPND,iCL8BOT.»l,tl ; Chock lor Input 

9$ ;Error rotnrnT 

CLSBVF.IS ;Cot nuabor ol charactora to road 

;Nako auro orror Hag la «tf 
g$ ;Iotum 11 no CL Input ponding (CL8BUF-0) 
#AiEA.#CLCHAN,#CLlBYT.#CLIBOF, I3.il ;load what la ponding 
9$ ;Error roturnT 

13.TT0CNT :8ot nuabor ol charactora to dlaplay 
iTTOBLI.IO ;Polnt to EMT arg block to 
STB :DlBplay kS ehara en tho tonlnal 



»(: 



lETU&N 



AlEA: 
TTOBLX: 

TTOCHT: 

CLSBVF: 

CLIBUF: 

CLOBUF: 

CLOBND 

TTIPTI: 

TTOPTl: 



.NLIST BEX 
.BLIW 10 



.BYTE 
.WOID 
.ffOID 
.VOID 
.BLKV 
.BLEW 



0,114 

CLIBDF 





128. 

40. 



.WOID CLOBUF 
.VOID CLOBUF 
.LIST BEX 



Qanoral purpoao BMT arg block 

ENT arg block to aond * el chare to TT 

Point to chare recelTod Iroa CL 

Count ol ehara to be dleplayed 

1 word CL atatue buller 

Can hold up to 26S charactora 

CL output ring buller 

rirat location paet CLOBUF 

Index Into buller lor next Input char 

Index Into buller lor next output char 



.END 



8TAET 
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7.2 RK06/RK07 handler (DM) 

The DM device handler .SPFUN function codes 876 and 377 attempt to return a status code into the first 
word of a user buffer which is one word longer than the actual transfer size. This is incompatible with 
system I/O mapping. It appears that the only system utility program which issues these functions is DUP 
(SQUEEZE and INITIALIZE commands). If it is necessary to use the MAPIO option with the DM device 
handler, it is recommended that both INITIALIZE and SQUEEZE commands for DM units be issued onlv 
under RT-11. ' 

The DM handler supports 22-bit (as well as 18-bit) Q-Bus I/O with the DILOG DQ215 and the Emulex 
SC02C controllers. 

7.3 DU (TMSCP) handler 

The BYPASS special function (371) is not supported with the DU (MSCP) device handler on extended 
Unibus hardware. 

7.4 IEEE GPIB handler (IB) 

The normal IB supplied subroutines attempt to open the IB device on decimal channel numbers 16 17 18 
and 19. TSX-Plus normally allocates 20 (decimal) channeb and allows these IB subroutines to execute with- 
out changes. Non-standard configurations where multiple devices may be used and more than 20 (decimal) 
channek are required are not supported. 

A change is also necessary to the IB device handler to alter the mapping register used from PARI to PAR6 
i^cv^nr''^'°'' ''''''"''"'''^ ^^^'""^ handlers use of PARs discussed in the chapter on Device Handlers in the 
u '^ev'rf^''"" A/anai7er', Guide. See the Patching and Building TSX-Plus Device Handlers chapter in 
lr!L Installatton Guide for information on how to build an IB handler which will function with 

TSX-Plus. 

The IB subroutine IBSRQ is implemented in the DEC IB handler as a subroutine caU from the handler 
directly to the user code region. Since TSX-Plus does not load any user job in the same map region as the 
operating system, the call will execute part of the operating system, usually resulting in a fatal system error 
or halt. Therefore, the IBSRQ call is unsupported in TSX-Plus. 

7.5 Logical subest disk handler (LD) 

The LD device handler is implemented as an overlay in TSX-Plus and does not use the RT-11 LD handler 
However, its implementation is compatible with logical subset disks from RT-11 so that LDs created mounted 
and used under either operating system may also be accessed under the other, using the same commands. 
The TSX-Plus LD pseudo-handler accepts two special function codes: 372 to read the LD translation tables 
and 378 to return the device size. A request to return the device size returns the size of the file which is 
mounted as the LD unit to which the channel is open on which the .SPFUN was issued. UnHke RT-11 a 
channel must be open to a valid LD unit in order to read the LD translation tables. That is, some unit must 
be mounted and accessible and a channel opened to such an LD unit by a successful .LOOKUP (usually 

ri?"1prJTM '"'•''^^•/t.' '/'^^^^'^'i^'^ '"-^^^ ^^' *" ^""^^^^ LD units is returned, regardless of the unit to which 
the .SPI'UN IS issued. If the unit is not currently mounted, but was previously, some of the information may 
be retained from the previous mount. The information is only valid if bit 15 is set in the LD unit's status 
word. Ihe LD translation tables are read-only, regardless of the value of the special function word-count 
parameter; both reads and writes to the LD translation tables are treated as reads and will return the 
translation tables into the user buffer. 
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The contents of the LD translation tables returned by .SPFUN code 878 differs according to the version of 
RT-lTfrom which TSX-Plus was started. If the RT-11 version is 5.4 or later, then the table ^.P^e ;;ced by 
fwo additional words and one of the status bits is redefined. If the RT-11 version is 5.8 or earlier, then the 
table begins immediately with the LD unit status words and one of the status bits is redefined, otherwise 
the translation tables are the same. The format of the table is as follows: 



Size 



2 bytes 
1 byte 
1 byte 
8*2 bytes 
8*2 bytes 
8*2 bytes 
8*8 bytes 



Use 



RAD50 value of «LD " if RT-11 V5.4 or later, absent if not 
Number of LD units available (8) V5.4 or later, absent if not 
Unused V5.4 or later, absent if not 
Status word for each LD unit 
Starting block number of each LD 
Number of blocks in each LD 

Device:Filename.Extension in RAD50 of each LD (device name in- 
cludes unit number) 



The status word for each LD unit is defined as follows: 



Bits 



15 
14 
18 
10-8 
5-1 



Mask 



100000 

40000 

20000 

8400 

76 



Meaning 



Flag bit if LD unit is currently mounted 

Flag bit if LD unit is read-only (RT-11 V5.4 and later) 

Flag bit if LD unit b read-only (RT-11 V5.8 and earlier) 

Unit number of device holding LD file 

Index of device holding LD file 



Example 



.TITLE LSTBL 

Exupl* progrim to dliplaf LD truiilatlon tabl«« 

.MCALL .PEINT. .EXIT, .LOOIDP, .CLOSE. .SPFUW. .SKU. .HEU 

.DSiBL GBL 

.6L0BL P&IE60.P1T0CT 



BEL 
NLDS 



« 7 
- 8. 



; ASCII BELL eharaetar 
;Dafault nuabar of LD units 



Start by trying to llnd a ehannal to any LD unit, 
Can only roa4 tranalatlon tablts aftar gattlng 
a ehannol (any channol) to tho handlar. 



STUT: 



.8EU 

.LOOKUP «AREA,fO,fDBLK 



BCC 

INC 

CNP 

BL08 

.PlIMT 

Bl 



11 

DBLI 

DBLK.f'lLDr 

START 

iNOLDS 

91 



:Trap LOOIUP arrora 

;Ia thla LD unit Bountadt 

; Branch If ao 

;If not, try tha naxt ona 

;Paat last poaalblt LD yotT 

;Iaap looking if not 

:OopB, no LDa en Una 

sQo axlt 



Nov try to raad and dlaplay tha LD tranalatlon tablat 

i|: .REil :laanabla ayatea arror trapping 

.8PFU1I •AIEA.i0,i372.#B0Fr,il,f0 ;Oat tranalatlon tablaa 

BCC 2$ ;Br If SPFim 01 

•PlIHT #BADSPF ;Eloa raport arror 

Bt 8l il^^ V^^^ 
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3$: 

M: 

9$: 



CALL 



SHOLDS 



.CLOSE fO 
.EXIT 

LD tranilatlon tabl* fozmat It; 



;Dlspla7 LD truislatlon tablaa 
;Cloa« ehannal to LD unit 



IF 



IT-VEESION >« 5. 
.lADBO /LD / 
.BYTE NLDS.O 



4 :ThaBa 2 vordi arc abaant If <1T VE.4 

;1 word of doTlca nasa 

:1 b^ta « i LD nnlta. 1 bjta 



END IF 
STATUS 



.BLEV NLDS 



INUSE 

tONLY 

lONLY 

DVUNIT 

DVINDX 



100000 
040000 
020000 
003400 
000076 



Unit 
Unit 
Unit 



Nota: 

ST All 
SIZE: 
MANE: 



;1 vord/unlt LD atatua 
la allocatad maak In STAT word 
la raad-onl7 IT VE.4 and latar 
la road-only IT V6.S and aarllar 
Naak for roal darlca unit i 
Haak for raal darlca indax # 
Tha following vorda aay contain raaldua from praTloua aounta. 
Thay ara only aaanlngful If tha IHUSE flag li aat In STATUS. 
.BLIV NLDS :1 vord/unlt raal disk atart block i 

.BLIV NLDS ;1 vord/unlt doTlea alia (blocka) 

.BLIW 4*NLDS :4 vorda/nnlt nama of flla aountad 



SHOLDS: NOV 
NOV 
CNP 
BNE 
1ST 
NOV 
BIC 



i$: 



3t: 



SHOILO: 



.PIINT 

NOV 

NUL 

NOV 

ADD 

NOV 

ADD 

NOV 

ADD 

NOV 

CALL 

INC 

ADD 

ADD 

ADD 

SOB 

lETUEN 

NOV 

CALL 

.PEINT 

NOV 

CALL 

.PEINT 

NOV 

CALL 

.PEINT 

NOV 

CALL 

.PEINT 

NOV 

CALL 

.PEINT 

NOV 

CALL 

NOV 

CALL 



•NLDS.ES 

f BUFF. El 

(El).ff'ELD 

II 

(ED* 

(E1)*.ES 

t*C377,ES 

fTBLHDE 

«2,E6 

ES.E6 

El. STATS 

E6.E1 

E1.6TETS 

E6.E1 

El. SIZES 

E1.E6 

»*ELD0.E1 

SHOILD 

El 

#2. ST ATS 

#2.STETS 

•2, SIZES 

ES.2I 



Ei.EO 

PETE50 

iSP2 

•ST ATS, EG 

PETOCT 

iSP2 

•STETS.EO 

PETOCT 

«SP2 

•SIZES, EO 

PETOCT 

•SP2 

(ES)^,EO 

PETE60 

•COLON 

(E6)«.E0 

PETEEO 

(EE)^,EO 

PETEEO 



;AaBnBa 8 LD unlta 

; Point to ratumad LD tabla 

:Nav tabla fonutt 

;Br If not 

;Sttp oTar EADEO LD 

;Gat count of LD unlta (lov byta) 

:Will ba 8. undar TSZ-Plua 

; Explain dlaplay 

if bytaa par unit for STATUS, 8TAET, SIZE 

:# bytaa par tabla for STATUS.STAET.SIZE 

:Sat ptr to atatua vord Toctor 

iStap ptr oTor atatua vorda 

;Sat ptr to atartlng block ractor 

;Stap ptr orar atarta 

;Sat ptr to alia Toctor 

;Uaa EE aa ptr to naaaa 

{Currant unit naaa 
:Dlaplay aach unit 
;Stap aach polntor to naxt unit 



: Through tha antlra llat 



; Dlaplay unit naaa 



; Dlaplay unit atatua 



:Dlaplay unit atartlng block fa 



sDlaplay .DSI fila slsaa 



iDlaplay DEV:FILNAN.EXT 
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.PUNT 


iDOT 






NOV 


(E6)«.I0 






CALL 


PIT160 






•PEINT 


•CELF 






lETDIN 






' 


.NLIST 


BEX 




AlEA: 


.BLIV 


10 


:6ontral ENT arg block 


DBU: 


.IAD60 


/LDO/ 


;LD doTlco nuo 




.VOKD 


0,0.0 




BUFF: 


.BLKV 


266. 


;At loast 2* (2« (8*3) +(8*4)) 


STATS 


.WOiD 





iPolntor to Statue worda 


STITS 


.VOEO 





;Polnt«r to Starting bloeki 


SIZES 


.VOEO 





;Polntor to Sliaa 


HOLDS 


.ASCIZ 


/Sorry, no LD 


• currtntly ■ountod./<7> 


BADSPl 


': .ASCIZ 


/Oops. .SPFUH 


trrorl/<BEL> 


CILF: 


.ASCIZ 


II 




SP2: 


.ASCII 


1 l<200> 




COLON 


.ASCII 


/:/<200> 




DOT: 


.ASCII 


/./<200> 




TBLHDl 


I: .ASCII 
.ASCIZ 
.LIST 


/Unit Statu! 
BEX 


Offiot Slso DEV:FILNAN.EZT/<1B><12> 
/ 






.EVEN 








.END 


START 





Some of the information available in the LD translation tables may be obtained without opening a channel 
to an LD unit by using EMT 875, function code 4,185. This EMT returns five words of information for each 
LD unit: fo\xr words of RAD50 DevicerFilename.Extension and one word of status. The status word has two 
bits defined: bit (mask 1) is set if the unit is read-only; bit 1 (mask 2) is set if the unit is not currently 
accessible (for example if it is mounted within an outer LD and the outer LD has been dismounted). 

Other EMT's are also available to mount and dismount LD units from within programs. See the descriptions 
of EMT 375 functions 3,135 4,185 5,135 and 168 in Chapter 4. 

7.6 MU (TMSCP) handler 

The MU handler is not supported on extended Unibus hardware. The BYPASS special function (871) is not 
supported for use with the MU handler. 



7.7 Virtual memory handler (VM) 

The virtual memory handler (VM) allows memory which is not allocated for use by the operating system to 
be used as a RAM based pseudo-disk device. VM may not be used to contain either the swap or spool system 
files due to the nature of system completion routine nesting. When VM is used as a spool or swap device, 
unpredictable operation may occur resulting in fatal system errors and system halts. VM is implemented 
as a device handler (VM.TSX) and not as a system overlay (like LD and CL). VM.TSX is not derived from 
the RT-11 VM handler (there is no VM.SLP). As a device handler, it requires an entry in the device tables 
and must be included with a DEVDEF macro during system generation. 

The VM handler uses the memory space above the top of memory used by TSX-Plus. TSX-Plus can be 
limited to using less than all installed memory by specifying the TSGEN MEMSIZ parameter. See the TSX- 
Plus Inetallation Guide for details on the MEMSIZ setting. Since a memory access is quite a bit faster than 
a disk access, VM can be use for greater speed in locating and reading files which are frequently accessed. 
Since most machines will lose the contents of memory during a power outage, VM should be restricted to 
read-only, scratch, or executable files. It may be used to speed the execution of heavily overlaid programs 
or store temporary intermediate sort or work files. 
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After TSX-Plus is started, VM must be initialized before it can be used (except see using with RT-11 
VM below). Since VM is implemented as a block structured device, and each block contains 512 bytes, 
the number of blocks available to VM will be two times the number of kilobytes allocated. The directory 
does require some storage and therefore the number of blocks reported after initialization will be slightly 
smaller than this total. For instance, in a system which contains 512 Kb total physical memory and with 
MEMSIZ=256., VM will have 256 Kb available. After initialization, a directory of VM will then show slightly 
less than 512 blocks. 

VM will normally calculate the correct base address to use to be just above the last address used by TSX- 
Plus. You may increase this base address. The format of the SET command used to adjust the base address 
used by VM is: 

SET VM BASE=nnnTinn 

where nnnnnn represents bits 6 through 22 of the base memory address (in octal) which VM is allowed to 
use. However, if you specify a base address below the top address of TSX-Plus, VM will dynamically adjust 
this ba^e address back above the top of TSX-Plus. For example, if you wish to set the base address of VM 
to start after the first 512 Kb, then nnnnnn should be 20000 since the memory address is 2000000 (octal). 
Any time a new base address is defined, VM should be initialized. 

VM will normally calculate the correct top address to use to be at the absolute top of physical memory. You 
may decrease this top address. The format of the SET command used to adjust the top address used by 
VM is: 

SET VM TOP=nnnnnn 

where nnnnnn represents bits 6 through 22 of the top memory address (in octal) which VM is allowed to 
use. For example, if you wish to set the top address of VM to end at 1280 Kb, then nnnnnn should be 
50000 isince the memory address is 5000000 (octal). Any time a new top address is defined, VM should be 
initialiieed. 

You may also use the same memory region which was defined as VM under RT-11. In order to do so, you 
must make sure that the MEMSIZ parameter restricts TSX-Plus to use of memory below the existing RT-11 
VM bajse or else it wiU be corrupted during the TSX-Plus initialization phase. You must also be careful 
to SET VM BASE and TOP to match the settings used under RT-11. If you match the TSX-Plus VM to 
overlay an existing RT-11 VM, then the contents will be intact and data stored there while running RT-11 
will be available after starting TSX-Plus. 

VM accepts two special functions: 872 to return two words of VM status information; and 378 to return the 
device size in blocks. For function 872, the first word returned in the user buffer is the current base of VM 
(the actual 64 byte block number, not the value set in the handler) and the second word is the current VM 
top. 

Example 

.TITLE VNSHDW 

; Dnoniitrat* .SPFUN to rtturn VN Infonutlon 

.MCALL .SPFim, .PRINT, .EXIT, .LOOKUP, .CLOSE 

.DSABL GBL 

.GLOBL PETOCT.PITOEC 

VHSHOW - S72 ;8PPDH cod* to roturn VM itata 

» 

STUT: .LOOKUP iA&EA , *0 , «DEVNAN iOpon ehumol to TN 

BCC II ;Br 11 01 

.PKINT fLIPEU ;Eloo eo>plaln 

Bt B| :And abort 

II: .SPFUN t AREA, #0. #372, #BUFFE1,#0.#0 ;Try to g«t ¥M itatt 
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BCC 


2$ 


;Br If 01 


11$: 


.PEINT 


•SPFE&I 


;Eltt complain 




Bt 


01 


;And abort 


21: 


.PIINT 


iBASE 


:Ditpla7 VN Info 




NOV 


BUFFER. to 


;0ot bait ralua (In 64 bytt bloeki) 




CALL 


PRtOCT 






.PEIKT 


iTOP 






NOV 


BUFFEI-»2,10 


:Qat top Taluo (In 64 bjto blocki) 




CiLL 


PKTOCT 






.SPFTO 


«AREA,iO,*S7S.iBUFFEi,#0,fO :Gtt VN tist 




BCS 


HI 


;CoapIaln on orror 




.PIINT 


fSIZE 






NOV 


BUFFE&.IO 


;Gat ■1x0 In blocki 




CALL 


PKTDEC 




9»: 


.CLOSE 
.EXIT 


to 


;Cloto channtl to VN 


• 


.NLIST 


BEX 




URA: 


.BLIV 


10 


;Gon«ral BNT arg block 


DEVNAN: 


.1AD50 


/VNO/ 


;Non-fll« atrncturod lookup 


BVFFBl: 


.VO&O 


0.0,0 


;latarn SPFUN data bora 


LIPEU: 


.ASCIZ 


/.LOOIUP trror/ 




BPFEIi 


.ASCIZ 


/.SPFUN trror/ 




BASE: 


.ASCII 


/VN Bas*-/<200> 




TOP: 


.ASCII 


/ Top-/<200> 




SIZE: 


.ASCII 


/ Slxt-/<200> 






.LIST 


BEX 






.END 


STAIT 
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7.8 Communications handler (XL) 

The RT-11 VTCOM utility communicates with host systems through a device named XL. You may either 
install and use the XL device handler or you may make a logical assignment of XL to a current CL unit. 
If you use XL.TSX, then the interface is dedicated solely to use with the XL device, whereas by defining 
the line as a time-sharing line and then "taking it over" as a CL unit, you gain increased flexibility in 
utilization of the port. In addition, XL is restricted to DL(V)11 type interfaces, while CL may be used on 
any type of serial interface supported for terminals. This allows you to alter the port speed with a keyboard 
command (on programmable rate interfaces) and monitor the line's state with SYSMON. Because of this 
increased flexibility, we strongly recommend the use of CL units rather than the XL device handler. For 
more information on SET CLn commands see the TSX-Plus User's Reference Manual. Also see the other 
sections in this chapter for use of CL with VTCOM and for information on programming with CL. 



7.9 Spooled devices 

Output sent to spooled devices with .WRITx EMTs is intercepted by the TSX-Plus spooling system and 
transferred to a system managed disk file. Data in this file is then supplied to the handler for the spooled 
device by the system as needed. For a more general discussion of device spooling, see the TSX-Plus User's 
Reference Manual. 

Data blocks in the spool file begin with two words of header information, followed by up to 508 bytes of 
data. The first header word is a pointer to the next block in the spool file for thb data stream. The second 
word is the number of data words in the current block. Information such as spool file starting blocks, file 
names and output device is stored and managed elsewhere by the system. 

Requests to read input from spooled devices are not intercepted or otherwise aflFected by the spooling system 
. Special function requests of all kinds to spooled devices are similarly ignored and unaff'ected by the spooler. 
Thus, in order to have output to a spooled device actually spooled, the I/O request should ordinarily be done 
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via th« .WRITW EMT. The fact that .READx and .SPFUN requests bypass the spooler is not ordinarily 
important to print devices such as LS and LP. However, when programming I/O to special device handlers for 
devices like plotters and modems, it is important to remember that only .WRITx requests utilize spooling. 
An example of a potentially undesireable effect of spooling can be seen by running the VTCOM program 
with XL assigned to a spooled CL unit. Since VTCOM uses a .WRITC to transmit data, it is intercepted by 
the spooler and buffered through the spool file. No information will actually be sent to the CL unit until the 
block is full (508 bytes) or the channel is closed. Because of this unusual behavior, use of VTCOM through 
a spooled CL unit is not recommended. 

In somie cases, it may be desirable to bypass the spooling system. For special device handlers and for CL 
units which support special function write requests, .SPFUN requests can accomplish this. Since LS and LP 
do not (currently) support special function requests, another approach must be used. The spooling system 
identifiies spooled devices both by device name and unit number. Thus, if LP (equivalent to LPO) is spooled 
then only writes to LPO will be spooled. Since the LP device handler ignores unit numbers, writes to LPl 
will bypass the spooler, but wUl be handled normally by the LP handler. The same holds true for LS - 
writing to LSI bypasses spooled LS. Note that CL does support device units and thus you cannot bypass 
the spooler on spooled CL units by selecting a different unit number. 

Since mixed output will result if two jobs write to a non-file-structured device like LS, LP or CL unless 
managed by the spooling system, care must be taken to prevent this when bypassing the spooler. We 
recommend that non-spooled serial devices or spooled devices which are being bypassed be allocated by the 
job before writing to them. 
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Chapter 8 

Real-Time Program Support 



TSX-Plus provides a real-time program support facility that allows multiple real-time programs to run con- 
currently with normal time-sharing operations. The basic functions provided by this faciUty are summarized 
below: 

• The ability to map the I/O page into the user's virtual memory region so that device status and control 
registers may be directly accessed by the program. 

• The ability to connect device interrupt vectors to program interrupt service routines running at fork 
level or to program completion routines running at user-selectable priority levels with full job context. 

• The ability for a program to lock itself in memory so that rapid interrupt response can be assured. 

• The ability for a program to suspend its execution until an interrupt occurs. 

• The ability to set execution priorities for tasks. 

• The ability to convert a virtual address within the job's region to a physical address for DMA I/O 
control. 

• The ability to map a virtual address region to a physical address region. 

• The ability for a program to declare a list of addresses of device control registers to be reset when the 
program exits or aborts (.DEVICE EMT). 

Most of the features associated with the real-time facility are a basic part of TSX-Plus, but the ability 
to attach interrupt service routines or interrupt completion routines to interrupt vectors is optional during 
system generation. 
Special privilege is required to perform some of the requests described in this chapter. For example: 

REALTIME privilege is required to use the .DEVICE request or to get exclusive system control; 
MEMMAP privilege is required to map to the I/O page or other specific locations in physical memory; 
FSWAPM privilege is required to lock a program in memory. 

The real-time facilities are available to both normal jobs controlled by time-sharing lines and to detached 
jobs. Note that detached jobs that are specified during system generation for automatic startup run with all 
privileges, unless specifically changed; detached jobs started by time-sharing users have the same privilege 
as the job starting them. 
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8.1 Accessing the I/O page 

A basic facility required by most real-time programs is the ability to access the PDP-11 I/O page (160000- 
177777) which contains the device control and status registers. Under TSX-Plus, addresses in this range 
are normally mapped to a simulated RMON or may be used ais normal program space. This is done since 
many old programs require direct access to certain system values at fixed offsets into RMON, although 
recent programs should access these values with the .GVAL and .PVAL EMTs. TSX-Plus provides several 
EMTs to deal with mapping of the I/O page and accessing locations within it. These are dbcussed below. 
See Chapter 2 for a discussion of various mapping techniques which may be used under TSX-Plus. The 
/lOPAGE switch to the R[UN] command may also be used to map a program's PAR 7 to the I/O page. 

A TSX-Plus real-time program can access the I/O page in one of two ways: It can cause the program's 
virtual address region in the range 160000 to 177777 to be mapped directly to the I/O page so that it can 
directly access device registers; or it can leave the virtual address range mapped to the simulated RMON 
and use a set of EMTs to peek, poke, bit-set and bit-clear registers in the I/O page. It is much more efficient 
to directly access the device control registers by mapping the I/O page into the program's virtual address 
region than to use EMTs to perform each access. However, this technique will not work if the program must 
also directly access offsets inside RMON. The correct way for a program to access RMON offsets is to use 
the .GVAL EMT which will work even if the I/O page is mapped into the program region. 

8.1.1 EMT to map the I/O page into the program space 

The following EMT can be used to cause the program's virtual address region in the range 160000 to 177777 
to be mapped to the I/O page. Use of this EMT requires MEMMAP privilege. The /lOPAGE switch to the 
RjUN] command may also be used to map a program's PAR 7 to the I/O page. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 5.140 

The I/O page mapping set up by this EMT remains in effect until the program exits, chains, or the EMT 
described in the next section is used to remap to RMON. Note that completion routines and interrupt service 
routines run with the same memory mapping as the mainline code of the job. 

The .GVAL EMT with offset value -8. may be used to determine if PAR 7 is currently mapped to the I/O 
page or to the simulated RMON. See the description in Chapter 4 of the special use of .GVAL for further 
information. 

Example 

.TITLE NAPIOP 

.ENiBL LC 
:D»onitr«t» T8X— Pins EMTi to up to tho I/O pago and back to INON 

IMDNST - 64 SSYSCOM location holdlnf baso ol IMON 

CONFIG « SOD :Flxod offaot into INOH ol CONFIG word 

tCSi - 176640 ;8arlal lino ICSl addrota 

iBUF > lCSl+2 ;Llnt Input bufftr addrtaa 

CTELC - S ;-C 

.MCALL .PilNT.. EXIT,. TTTOUT.. GVAL 

.GLOBL PITOCT 

8IA1T: CALL 8U0NAP ;Dlaplay eurront PU 7 mapping 

CALL SHODAT :Dononatrato IMON mapping 

.PlIKT tlOPMSG jSay vo aro awltchlng to 1/0 pago mapping 

MOT tMAPIOP.lO :Polnt to EMT arg block to 

EMT 376 ;Map to I/O pago 

BCC 11 ; Branch If OX to map 

.PilNT fNOPilT ;Toa aro not allowed to do that 
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1$: 



21: 



3$: 



SHONAP: 



SHODAT: 



NAPIOP: 

MAPNON: 

A&EA: 

CS&SAV: 

CU&NAP: 



C&LF: 

TOiNON 

T0I0P6 

NAPN80 

CNFGIS 

TYPE: 

I0PN86 

GOBACI 

NOP&IV 



.EXIT 

CALL 

.PUNT 

NOV 

CLI 

T8TB 

BPL 

NOVB 

CMPB 

BEQ 

.ITTOUT 

Bl 

NOV 

.PEINT 

NOV 

ENT 

CALL 

CALL 

.EXIT 

.PUNT 

.6VAL 

ASL 

.PUNT 

lETUlN 

.P&INT 

NOV 

NOV 

CALL 

.PUNT 

lETUUi 

.BYTE 

.BYTE 

.WO&D 

.VOEO 

.VOID 

.WOiO 

.NLIST 

.A8CIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCII 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCII 

.ASCIZ 

.END 



SHOMAP 

iTYPE 

•ilCSE.CS&SAV 

t«RCSl 

«*iCS& 

21 

tfiBUF.iO 

lO.iCTELC 

31 

2$ 

CS&SAV, ««&CSK 

tCOBACX 

fNAPNON.lO 

S7E 

SHOMAP 

SHODAT 

•NAPNSG 
iALEA.«-8. 
10 
CU&NAPdO) 

tCNFGIS 
«#&N0NST,IO 
CONFIG (&0), to 
PITOCT 
tCtLF 



Display currant PAl 7 mapping 

Proapt for Input froa I/O page 

Sara a copy of current CSl 

Dlaabl* Intorrnpta on aarlal lino 

la anything arallablo froa tho lino 

No, koop chocking 

Got tho now charactor 

Should wo quit? 

Quit on *C 

Dliplay tho charaetur 

And ropoat 

leitoro original CSE 

Say wo aro rotnmlng to original mapping 

Point to EMT arg block to 

Nap back to alBulatod INON 

Dliplay currant PAt 7 mapping 

And proTO wo aro back 

; Currant mapping prafaca 

:What la our currant PAl 7 mapplngT 

:ConTart to word off sot 

;Show which ono It lu 

:Profaco conflg Taluu 
:Plck up point or to INON baao 
;Got tho eurront CONFIG Taluo 
:Dlaplay it 



;ENT arg block to map to I/O pago 
;ENT arg block to map to INON 
:ENT arg block 

;SaTo CSl for raateratlon on axlt 
: Currant mapping maasaga tabla 



6,140 

6.140 

10 



TOINON 

TOIOPG 

BEX 

// 

/slmulatad INON./ 

"I/O paga." 

/PAl 7 la enrrantly mappad to /<200> 

/Curront Taluo of CONFIG word in aimulatod INON la /<200> 

/Charactora ontorod on aorlal lino will bo dlaplayod horo:/ 

<12>"Now awitching PAl 7 mapping to tho I/O pago." 

<16><12>/lotnrnlng PAl 7 mapping to slmulatad INON./ 

/laal-tlma aupport not apodflod during TS6EN or / 

/uaor not prlTllogod./ 

8TA1T 



8.1.2 EMT to remap the program region to the simulated RMON 

The following EMT can be used to cause the virtual address mapping region of the job in the range 160000 
to 177777 to be returned to normal mapping if it had previously been mapped to the I/O page. Use of this 
EMT requires MEMMAP privilege. The form of the EMT is: 

ENT 376 

with RO pointing to the following argument area: 

.BYTE 6.140 



Example 

See the example program MAPIOP in section 8.1.1 on mapping the I/O page into the program space. 
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8.1.3 EMT to peek at the I/O page 

The following EMT can be uaed to access a word in the I/O page without requiring the job's virtual address 
region to be mapped to the I/O page. (Note that the .PEEK and .POKE EMTs can also be used to access 
parts of the I/O page. See Chapter 12 for more information on the effects of the .PEEK and .fOiSJL H/Mis 
with TSX-Plus.) Use of this EMT requires MEMMAP privilege. The form of this EMT is: 



ENT 



375 



with RO pointing to the following argument area: 



.BYTE 
.WORD 



1,140 
addreaa 



where addrett is the address of the word in the I/O page to be accessed. The contents of the specified word 
in the I/O page are returned in RO. Note that with this and other EMTs that access the I/O page, if an 
invalid address is specified, an error will result with the message: 

?MON-F-K«rnel modn trap within TSX-Plu« 



Example 



.TITLE PEEIIO 
.ENABL LC 
:De«onBtr»t« TBI— Plni EKTt to p««k «nd pok» into tht I/O paf« 

:*c 

;Poliitar In STSCON um to start of IMOR 
:Flxod off tot into INON of conflg word 
sStrlal lino ICSl addrtoo 

:Llno input buffar addroto 
TOnT..GVAL 

;Dlapla7 earront Pit 7 sapping 

;DoBonstrato INON sapplnt 

;Point to EMT arg block to 

;Pttk into tho I/O pago 

; Branch if 01 

;Toa art not allovod to do that 



SaTO a copy of earront C81 

Vant to dliablo intormpto 

Point to ENT arg block to 

Pokt a valQO into tho I/O pago 

Should not bo orror if pook vorkod 

Prom>t for input froa I/O pago 

Point to ENT arg block to 

Chock tho ICSl 

lo anything arailablo froa tho lino 

No, koop chocking 

Point to tho rocoiTtr buffor 

Point to ENT arg block to 

Got tho input charaetor 

Should «o quitT 

Quit on *C 

Display tho character 

Point back to tho ICSl 

And ropoat 

Want to roitoro tho original C8I otatno 

Point to ENT arg block to 

laotoro tho CSl 

; Current sapping profaco 



CT&LC 


- S 




INONST 


- S4 




CONFIG 


. soo 




ICSl 


- 176B40 




IBUF 


. icsi^a 






.NCALL 


.PUNT.. EXIT,. 




.GLOBL 


PITOCT 


SI AIT: 


CALL 


8H0NAP 




CALL 


8H0C0N 




NOV 


ffPRREIO.lO 




EMT 


STB 




BCC 


1$ 




.PUNT 


tNOPIIT 




.EXIT 




11: 


NOT 


lO.CSlSAT 




CLl 


POIVAL 




NOT 


ffPOIEIO.lO 




ENT 


375 




.PUNT 


#TYPE 


2$: 


NOT 


iPEEIIO.lO 




ENT 


376 




TSTB 


10 




BPL 


a$ 




ADD 


#2. PEE ADD 




NOT 


fPEBIIO.lO 




ENT 


376 




CNPB 


lO.fCTlLC 




BEQ 


3« 




.TTTODT 






SUB 


•2,PEIA0D 




Bl 


31 


S(: 


NOT 


CSISAT.POETAL 




NOT 


tPOKEIO.lO 




ENT 


376 




• EXIT 




SHONAF 


: .PUNT 


•NAPNSG 
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SHOCON: 



PEEIIO: 

PEIADD: 

POIEIO: 

POXADD: 

POIVAL: 

AUA: 

CSISAV: 

CUINAP: 



CILF: 

TOINON 

TOIOPG 

NAPNSG 

CNFGIS 

ITPB: 

NOPII? 



.6VAL 
iSL 

• PUNT 
lETDlN 

.PUNT 
NOV 
NOV 
CALL 

• PUNT 
IBTU&N 
.BYTE 
.WO&D 

• BYTE 
.WOU) 
.VOU) 
.WORD 
.WO&i) 
.WOU) 
.ffOID 
.NLIST 
.iSCIZ 
.ASCIZ 
.ASCIZ 
.ASCII 
.ASCII 
.ASCIZ 
.ASCII 
.ASCIZ 
.END 



;¥hat it our eurrmt PAl 7 
:ConT*rt to word offiot 
;Shov which ono it !■ 



upplngT 



iA&EA,f-8. 

10 

C171NAP(I0) 

*CNFGIS 
•«U40NST.10 
CONFIG (&0). 10 
PITOCT 
iClLF 

1,140 

ICSl 

2,140 

ICSl 



10 



TOINON 

TOIOPG 

BEX 

// 

/■Imlatod INON./ 

"I/O pago." 

/PAl r la currantlr »*pptd to /<200> 

/Currtnt ralut of CONFIG word In ■laulatod INON It /<200> 

/Charaettra antortd on atrial Una will ba dlaplayad hara:/ 

/laal-tlma aupport not apaclfiad during T8GEN or / 

/uaar not prirllagad./ 

8TA1T 



:Prafaea eonfig ralua 
;Plck up polntar to INON baaa 
;Gat tha currant CONFIG ralua 
;Diapla7 It 

:EMT arg block to paak into tha I/O paga 

tAddraaa to ba raad 

:EHT arg block to poka into tha I/O paga 

;AddraBa to ba aodifiad 

:Vord to ba morad to POIADO 

;ENT arg block 

;8aTa CSl lor raatoratlon on axit 

i Currant sapping aaaaaga tabla 



8.1.4 EMT to poke into the I/O page 

The following EMT can be used to store a value into a cell in the I/O page without requiring the iob'. 

ENT 375 

with RO pointing to the following argument area: 

•BYTE 2,140 
.WORD address 
.WORD Talue 

where address is the address of the cell in the I/O page and value is the value to be stored. 

Example 

See the example program PEEKIO in section 8.1.3 on peeking into the I/O page. 

8.1.5 EMT to bit-set a value into the I/O page 

EMT 375 

with RO pointing to the following argument area: 
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.BYTE 3,140 
.WORD addrssB 
.WORD valu* 

.her. .a.r... i. the .ddre» of the cell in the I/O page and .«/« i. the value that wiU be bit-.et into the 

cell. 

Example 



.TITLE BISIO 
;l,.«n.tr™i'TSX--Plu. «T. *o bit-..t and blt-d.ar into th. I/O pa,. 



CTILC 
INONST 
INTHBL 
CONFIG 

icst 

IBUF 



8TUT: 



1$: 



SI: 



8H0NAP: 



8H0C0M 



PEEIIO 
PEI&DO 
BICIO: 



BISIO: 



UEA: 



9 

E4 

> 100 

> 300 
• 176640 
« ICSE-^a 

.NCALL 
.OLOBL 
CALL 
CALL 

MOT 
EMT 
BCC 

.PtINT 

.EXIT 

.PlINT 

NOT 

EXT 

T8TB 

BPL 

iOD 

NOV 

ENT 

CNPB 

BEQ 

.ITTODT 

SUB 

BE 

NOT 

ENT 

.EXIT 

.PEIHT 

.QTAL 

ABL 

.PEINT 

ISTUEN 

.PEINT 

NOT 

NOT 

CALL 

.raivT 

EET011I 

.BYTE 

.¥0EO 

.BYTE 

.WOED 

.ffOEO 

.BITE 

.WOED 

.VOED 

.BLEV 



;Pointar In 8Y8C0N araa to atart of ENOH 
:ECSE Inttrrupt onabla bit 
;Fixad oil tat into ENOH of eonlig word 
:8arlal Una EC8E addraaa 
:Llna Input boflar addraaa 
. PEINT .. EXIT ,. TTTOUT , . OTAL 

PETOCT 

8H0NAP ;Dlaplay currant PAE T Bapping 

8U0C0H -.DaBonatrata ENOI mppinf 

•.Want to elaar Inpnt intarmpta 

fBICIO.EO :Point to EMT axf block to 

375 ;Claar a bit in tha I/O paga 

II : Branch if 01 

iNOPEIT ;Ton ara not allovad to do that 



;0I. intarrupta ahonld ba dlaablad 

fXYPE ;Proiq»t lor inpnt fro« I/O paga 

fPEEIIO.EO '.Point to EMT arf block to 

376 ; Chock tha ECSE 

10 :Ia anything arailabla lro« tha lina 

2$ :No. kaap ehaeking 

ta.PEXAOD sPoint to tha racalrar buffar 

#PBBII0,EO ;Point to EMT arg block to 

375 ;Gat tha input eharactar 

:Talua froB paak la ratnmad in EO 

EO.iCTELC -.Should wa cpiltt 

31 ;Qult on *C 

•.Diaplay tha eharactar 

ta.PEIADD ;Point back to tha ECSE 

a| ;And ropaat 

;Want to aat inpnt intarrupta 
fBISIO.EO -.Point to EMT arg block to 
37B :8at a bit in tha I/O paga 

•NAPN80 ; Currant sapping prafaca 
•AEEA,i-8. ;*hat la our currant PU T aappingT 
HO -.ConTort to word eflaot 

CQENAP(EO) ;Show which ona it la 

iCHFGIS -.Pralaea eonfig Talua 
•iENOHST.EO ;Plek np pointar to ENOB baaa 
CONFIG (EO).EO ;Cat tha currant COKFIG Talua 
PETOCT ;DiBplay It 
fCELF 

J ^140 ;ENT arg block to poak into tha 1/0 paga 

tCSE ; Addraaa to ba raad 

4,140 :ENT arg block to eloar a bit in tha I/O paga 

tCSE ; Input atatua raglatar 

INTNBL ;Intarrupt anabla aaak 

S.140 ;B*T arg block to aat a bit in tha I/O paga 

(CSK : Input atatua raglatar 

INTNBL ;Intarrupt anabla maak 

10 :ENT arg block 
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C818AV: 


.WORD 


CHAIS: 


.BLKB 


EOV: 


.¥0&D 


CVINAP: 


.VOiD 




.VOED 




.NLIST 


CtLF: 


.iSCIZ 


TOIMON: 


.ASCIZ 


TOIOPG: 


.ASCIZ 


NJIPNSG: 


.ASCII 


CNFGI8: 


.ASCII 


TYPE: 


.ASCIZ 


NOPKIV: 


.ASCII 




.ASCIZ 




.EKD 



;SaT« CSl lor raitoratlon on oxlt 

6 ;fi char eat put baffar 

:Taralnator for .PUNT 

TO&NON : Currant mapping Boiaago tabla 

TOIOPG 

BEX 

// 

/alBulatad INON./ 

"I/O paga." 

/PAl T la currantly mappad to /<200> 

/Currant ralua of CONFIG word in alaulatad INON la /<200> 

/Charactare antarad on aarlal Una will ba dlaplayad hara:/ 

/Kaal-tlma aupport not apaclflad during TSGBN or / 

/uaar not prlTllagad./ 

8TA1T 



8.1.6 EMT to do a bit-clear into the I/O page 

The following EMT can be used to perform a bit-clear (BIC) operation into a cell in the I/O page without 
requiring the job's virtual address region to be mapped to the I/O page. Use of this EMT requires MEMMAP 
privilege. The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 4,140 
.WORD address 
.WORD value 

where address is the address of the cell in the I/O page and value is the value to be bit-cleared into the 
specified cell. 

Exani,ple 

See the example program BISIO in section 8.1.5 on doing a bit-set into the I/O page. 

8.2 Mapping to a physical memory region 

In certain circumstances, it is desirable to map a portion of virtual memory to a specific area in physical 
memory which is not in the I/O page. Possible examples would be ROM memory or an array processor. This 
mapping is done by altering one or more of the Page Address Regbters (PARs) for the job. Each PAR maps 
8192 bytes of memory from the virtual job space into physical memory. There are 8 PARs (8*8192=64 Kb). 
The region of memory mapped through each PAR is shown by the table below: 



PAR 


Virtual Region 





000000-017777 


1 


020000-087777 


2 


040000-057777 


8 


060000-077777 


4 


100000-117777 


5 


120000-187777 


6 


140000-157777 


7 


160000-177777 
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Use of this EMT requires MEMMAP privilege. The form of this EMT is: 

ENT 375 

with RO pointing to the following argument area: 



.BYTE 


17.140 


.WORD 


par-number 


.WORD 


phja-address 


.VORD 


size 


• BYTE 


access-type , cache-bypass 



where par-number is the number of the Page Address Register (PAR) that corresponds to the beginning of 
the program virtual address region that is to be mapped; phys-addrett is the physical address to which the 
virtual address is to be mapped. The physical address is specified as an address divided by 64 (decimal). 
That is, the physical address represents the 64-byte block number of the start of the physical region. Note 
that the physical address of any 64-byte block within a 22-bit physical address space can be represented in 
16 bits. 

Size is the number of 64-byte blocks of memory to be mapped through the virtual region. Each PAR can 
map up to 128 64-byte blocks of memory. If more than 128 blocks are mapped, successively higher PARs 
are set up to map the remainder of the region. 

AceesB-type indicates if the mapped region is to be allowed read-only access or both read and write access: 
O=read-only; l=read/write. 

Cache-bypaet causes hardware cache to be bypassed if this byte is 1. If this byte is 0, the normal case, 
then hardware caching is enabled. When eaehe-bypaet is set to 1, the actual effect is to set bit 15 in the 
Page Description Register (PDR) for each physical page mapped by this EMT. This can be important when 
mapping to devices such as bit-mapped graphic displays and array processors that interface to the Q-bus by 
dual-port memory. 

This EMT may be used to map any of the PARs to any physical address regions desired; even to map PAR 
7 to the I/O page. The use of this EMT does not affect mapping set up previously for other PARs. If size 
is sero (0), all PAR mapping is reset and the normal virtual address mapping for the job is restored. 

Note that this EMT is not equivalent to the extended memory EMTs used with PLAS (Program's Logical 
Address Space) requests and virtual overlays and virtual arrays. See Chapter 2 for a discussion of job 
environment and the appropriate RT-11 manuals for a more complete discussion of PLAS features. 

Note that disassociation of shared run-time regions (EMT S75, function 0,148 with a null name-pointer) has 
the side effect that regions mapped with this EMT will revert to the normal job mapping in effect prior to 
mapping the physical region. 

Example 

.TITLE NAPPHT 

.ENABL LC 

: Dmonitrat* TSX~Plas ENT to aap to (uij physical addrtit 

CTILC ■ S ;-C 

INTNBL ■ 100 :Intarnipt mabla bit 

1C8L - 176640 ; Serial lina ICSl addraaa 

iBVP - 1CS&42 :Lina Input bofftr addraaa 

. MCALt . PEINT . . EXIT , . TTYOUT . . CVAL 

8TA1T: .PtINT tNAPMSa ;8a7 va ara avitehlng to physical upping 

N0¥ iNAPPHT.IO :Point to ENT axg block to 

ENT S76 ;Nap to physical ■saory 

BCC II :Branch if 01 to map 

.PIINT fNOPIIT :Tou ara not allovad to do that 

.EXIT 

1$: .PIINT iTYPB :ProMpt for input froa I/O pago 

BIC flNTNBL.ttlCSl :Disabl« Intarrupts en serial line 
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21 



SI 



TSTB 

BPL 

NOVB 

CNPB 

BEQ 
.TTYOUT 

BR 

CLE 

NOV 

ENT 
.EXIT 
MJLPPHT: .BYTE 
.VOLD 
.VO&O 
.WORD 
.VO&D 
.NLIST 
.ASCIZ 
.ASCIZ 
.ASCIZ 
.END 



SIZE: 



NAPNSG : 

TYPE: 

NOPIIV: 



•»RCSI ;!■ anything arallablt from tha Una 

2$ :No. kaap chacklng 

•#RBDF,&0 :Oat tha naw eharactar 

lO.fCTliLC ; Should *a qultT 

St :Qult on *C 

;DlBpla)r tha eharactar 

2( ;And rapaat 

SIZE :If .alia la 0. original Mapping la raatorad 

iNAPPHY.IO :Polnt to EKT arg block to 

376 :taToka sapping to phyalcal addraaa 



:ENT arg block to map to phyalcal aamory 
:ramap PAt T 

: 17760000/04. addraaa to sap into PAI 7 
;alaa of raglon to be aappad - full 8 lb 
;accaBB O^raad-enly. l>raad/vrlta 



17,140 

7 

177600 

200 

1 

BEX 

/PAI 7 sapping la now dlractad to top of phyaleal unkorjj 

/Charaetara antarad on aarial Una rill ba dlaplayad hara:/ 

/You ara not prlrllogad to run thia prograa./ 

START 



8.3 Requesting exclusive system control 

The following EMT allows real-time jobs to gain exclusive access to the system while they perform time 
critical tasks. Use of this EMT requires REALTIME privilege. The form of the EMT is: 



]EMT 



375 



with RO pointing to the following argument block: 
.BYTE 14.140 

The efect of this EMT is to cause the TSX-Plus job scheduler to ignore all other jobs, even higher priority 
joba — including fixed-high-priority jobs until the real-time job relinquishes exclusive access control. Note 
that this is different (and more powerful) than giving the real-time job a higher execution priority because 
all other jobs are completely prevented from executing even if the real-time job goes into a wait state causing 
the CPU to become idle. 
The form of the EMT used to relinqubh exclusive system access is: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 15,140 

The following restrictions apply to a job that has issued an exclusive access EMT: 

1. The job is automatically locked in memory during the time it has exclusive access to the system. If 
you wish to use the TSX-Plus EMT that locks a job in the lowest portion of memory, that EMT must 
be executed before calling this EMT to gain exclusive access to the system. 

2. The size of the job may not be changed while it has exclusive access to the system. 

Exclusive access is automatically relinquished if the job exits or traps but is retained if the job chains to 
another job. 



Example 
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.TITLE STEALS 
.BMABL LC 
DcmoBitrat* TSX — Plus ENT fto ebt&la •xelnslT* •ystm control 



LUDIN 



S6 



JSW 


« 


44 


ITSPC 


- 


10000 


NOWilT 


■ 


100 




.NCALL 


.PEINT,.Tr 


STilT: 


MOT 


•TTSPCINOW 




• TTTOITT 


fLEADIN 




.TTTOITT 


• 'S 




.TTYOUT 


fLEADIN 




.TTTOUT 


#'D 




.PUNT 


iNSG 




MOV 


f STEALS. &0 




EMT 


S7E 


■ • • " 


.TITIH 






MOV 


iLETGO .&0 




ENT 


STB 




.EXIT 






.NLIST 


BEX 


STEALS: 


.BYTE 


14,140 


LETGO: 


• BYTE 


16.140 


NSG: 


.ASCII 


/Other Hit 




.END 


START 



:TSX-Plat program eoatrollod toralnal 

; option load-In charaetor. 

:Job atataa word addroaa 

:TT apoelal aodo bit In J8V 

:TT novalt bit In JSV 
TTYIN..EXIT 
JS¥ ;8ot TT apodal modo and novalt 

;blts In tho JSV 

;And mako TSX — Plaa ondorotand both 



; Prompt for Input 

:Polnt to ENT arg block to 

: Steal excluilTO ayatom control 

;Tlmo critical procoaalng gooa horo 

;Slmulatod horo with terminal Input 

;Polnt to ENT arg block to 

-.lellnqulah oxcIubIto ajatem control 



:ENT arg block for oxcIubIto BTitem control 
:ENT arg block to rollnqulah oxcIubIto control 
/Other UBorB are locked out until you proaa a ke7:/<200> 



8.4 Locking a job in memory 

In time-critic&l real-time applications where a program must respond to an interrupt with minimum delay, 
it may be necessary for the job to lock itself in memory to avoid program swapping. Use of the EMTs 
to lock a program in memory or to lock into low memory (below 256 Kb) or to unlock a program from 
memory (re-enable swapping) requires PSWAPM privilege. This facility should be used with caution since if 
a number of large programs are locked in memory there may not be enough space left to run other programs. 

TSX-Plus provides two program locking facilities. The first moves the program to the low end of memory 
before locking it; this is done to avoid fragmenting available free memory. This type of lock should be done if 
the program is going to remain locked in memory for a long period of time. However, this form of locking is 
relatively slow since it may involve program swapping. The second locking facility simply locks the program 
into the memory space it is occupying when the EMT is executed without doing any repositioning. This 
EMT has the advantage that it is extremely fast but free memory space may be non-contiguous. 

The form of the EMT used to lock a program in low memory (re-positioning if necessary) is: 



ENT 



375 



with RO pointing to the following argument area: 

.BYTE 7,140 
The form of the EMT used to lock a job in memory without repositioning it is: 

ENT 37B 

with RO pointing to the following argument area: 
.BYTE 13.140 
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Error 
Code 







Mean,mg 



Job does not have PSWAPM privilege 



Example 

See the example program ATTVEC in section 8.11.2 on connecting a real-time interrupt to a completion 
routine. 

8.5 Unlocking a job from memory 

When a job locks itself in memory, it remains locked until the job exits or the following EMT is executed. 
The form of the EMT used to unlock a job from memory is: 

lEMT 375 

with FLO pointing to the following argument area: 

.BYTE 10.140 

Example 

See the example program ATTVEC in section 8.11.2 on connecting a real-time interrupt to a completion 
routine. *^ 

8.6 Suspending/Resuming program execution 

The RT-11 standard .SPND and .RSUM EMTs are used by TSX-Plus real-time jobs to suspend and resume 
their execution. Frequently, a real-time job will begin its execution by connecting interrupts to completion 
routmes and doing other initialization and then wUl suspend its execution while waiting for a device interrupt 
to occur. ^ 

The .SPND EMT causes the mainline code in the job to be suspended. Completion routines are not affected 
and execute when mterrupts occur. If a completion routine executes a .RSUM EMT, the mainline code will 
contmue execution at the point following the .SPND when the completion routine exits. Refer to the RT-11 
Programmer's Reference Manual for further information about the use of .SPND and .RSUM. 

Example 

Routine '''''"'^^' ^'°^'''"' ATTVEC in section 8.11.2 on connecting a real-time interrupt to a completion 

8.7 Converting a virtual address to a physical address 

When controlling devices that do direct memory access (DMA), it is necessary to be able to obtain the 
physical memory address (22.bit) that corresponds to a virtual address in the^b. Note that a Job should 
lock Itself m memory before performing this EMT. The form of the EMT is: 

ENT 376 

with RO pointing to the following argument area: 
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.BYTE 0,140 

.WORD Tirtual-addresB 

.WORD result-buffer 

where virtual- addrcs. is the virtual address that is to be converted to a physical address and '•""J*-^"^^'- ^^ 
Tk. addresrof a two word area that is to receive the physical address. The low order 16 bits of the physical 
addresf- st^ed inTe fi.^^ word of the result buffer and the high order 6 bits of the physical address are 
stored in bit positions 4-9 of the second word of the result buffer. 



Example 

.TITLE PHY ADD 

: D»oiiitrat« I8X--P1U. EMT to eonT.rt a Tlrtu»l to a phyileal addrot. 
.MCALL .PUNT.. EXIT 

♦LOIJOB.M ;Polnt to EMT ar| block to 

S7B :Lock Job in Bomory 

II :Continno If 01 

iHOPIIV ;Bxplalii tho pxobloi 

2f ;Bnd qolt 

♦STEADD ;8»y whopt thla prograB vaa loadod 

•START ,10 ;6ot tho Tlrtual addrota 

PiTADD ;and display it to tho tomlnal 



8TA1T 



It: 



2<: 
PITADD: 



II: 



at: 



SI: 



LOXJOB: 
PET ADD: 
TIIAOD: 

BaFFEl: 

CKtEKD: 

NOPIIT: 
STIADD 



NOV 
EMT 
BCC 
.PIIHT 
BE 

.PEINT 
NOT 
CALL 
.EXIT 
NOV 
NOT 
EKT 
NOT 
NOT 
BIC 
NOT 
A81 
SOB 
NOT 
NOT 
NOT 
BIC 
iOD 
NOTE 
NOT 
ASl 
EOE 
BOB 
SOB 
.PEINT 
EETUEK 
: .BYTE 
.BITE 
.VOED 
.WOID 
.VOID 
.BLU 
.VOID 
.NLIST 
.ASCII 
.ASCII 
.EMD 



EO.TI&ADD 
tPHYADD,10 
376 

BUFFER. 11 
<BDFFER'»2>,12 

t*ci7eo,ia 

#4,13 

12 

13.11 

iCKREND,14 

#8.. 13 

11.10 

#*C7.10 

#'0,10 

10, -(14) 

#3,16 

12 

11 

16,31 

13,21 

14 



;Pnt tho Tlrtual addroaa into tho arg block 

;Polnt to ENT ar| block to 

;ConTort vlrtaal to phyaieal addrooa 

;lotrloTO tho low addrota 

:And tht high addroaa 

:Uao only bita 4-9 

: Throw away bita 0-8 



;Point to ond of charaetor oatpat boffor 

;Mood to eonwort 8 dlglta 

;aot a copy of low bita into 10 

:Naak out all bat low digit 

;ConTort to ASCII 

:Piit lew digit in output buff or 

; Shift OTor 3 bita to noxt digit 

;Low bit of high addroaa 

;lnto high bit of low addroaa 

:Do all 8 digits 

; Print out tho roault 



13.140 

0,140 



BUFFER 

0,0 

10. 



BEX 

/User not prirllogod./ 

/This prograB la loadad at START 

ST AIT 



;ENT arg block to lock Job in BtBory 

;ENT arg block to dotorBino physical addroaa 

: Tlrtual addroaa to bo lecatod 

; Location of 2 word roault buff or 

;Will hold low and high phyaieal addroaa 

:Buff07 to hold ASCII Taluo of addroaa 

:End of ASCII buffor 



/<200> 



8.8 Specifying a program-abort device reset list 

The standard RT-11 .DEVICE EMT is used by TSX-Plus real-time jobs to specify a list of device control 
registers to be loaded with specified values when the job terminates. This feature is useful in allowing real- 
time devices to be turned off, if the real-time control program aborts. The TSX-Plus .DEVICE EMT has 



8.9. SETTING PROCESSOR PRIORITY LEVEL 183 

the same form and options as the standard RT-11 .DEVICE EMT. Use of this EMT requires REALTIME 
privilege. See the RT-11 Programmer 't Refertnee Manual for further information. 

The connection between interrupt vectors and interrupt service routines or interrupt completion routines 
IS automatically dropped when a job terminates. The interrupt vector is then connected to the system 
unexpected mterrupt routine. If an address specified in a .DEVICE list corresponds to an interrupt vector 
connected to the job during job cleanup, then the vector is not connected to the unexpected interrupt routine. 

8.9 Setting processor priority level 

The following EMT allows a program to set the processor priority level. Use of this EMT requires REALTIME 
privilege. This EMT can be useful in a situation where it is necessary for a real-time job to block interrupts 
for a short period of time while it is performing some critical operation. On return from this EMT the job 
18 executing in user mode with the specified processor priority level. The form of the EMT is: 

EMT 37B 

with RO pointing to the following EMT argument block: 

.BYTE 16,140 
•WORD prio-level 

where pricUvcl should be 7 to cause interrupts to be disabled or to re-enable interrupts. Interrupts should 
not be disabled for a long period of time or clock interrupts and terminal I/O interrupts wiU be lost. 
Note that it is not possible to raise the processor priority level by storing directly into the processor status 
word from a real-time program because the PDP-11 hardware disallows modification of the PSW by a user 
mode program even if the program has access to the I/O page. 

Example 

Routine '""^""^^^ Pr^g^*^"^ ATTVEC in section 8.11.2 on connecting a real-time interrupt to a completion 

8.10 Setting Job Execution Priority 

Jobs may be assigned priority values in the range to 127 to control their execution scheduling relative to 
other jobs. The priority values are arranged in three groups: 

• the fixed-low-priority group consists of priority values from up to the value specified by the PRILOW 
sysgen parameter ^ ^^ »» 

• the fixed-high-priority group ranges from the value specified for the PRIHI sysgen parameter up to 127 

• the middle priority group ranges from (PRILOW+1) to (PRIHI-1) 

The current values for PRIHI and PRILOW may be determined with the SHOW PRIORITY command or 
from withm a program with a .GVAL request. The following diagram illustrates the priority groupT 



127 

PRIHI 

PRIDEF 

PRILOW 





Fixed High Priorities 



Normal Job Priorities 



Fixed Low Priorities 
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Job scheduling is performed differently for jobs in the fixed-high-priority and fixed-low- priority groups th«i 
for jobs with normal interactive priorities. Jobs with priorities in the fixed-low-priority group (0 to PRILOW) 
and the fixed-high-priority group (PRIHI to 127) execute at fixed priority values. That is the priority 
absolutely controls the scheduUng of the job for execution relative to other jobs. A job with a fixed priority 
is allowed to execute as long as it wishes until a higher priority job becomes active. 

The fixed-high-priority group is intended for use by real-time programs. The fixed-low-priority group is 
intended for use by very low priority background tasks. Normal time-shaxing jobs should not be assigned 
priorities in either of the fixed priority groups. 

The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be used by normal, inter- 
active time-sharing jobs. Jobs with these assigned priorities are scheduled in a more sophisticated manner 
than the fixed-priority jobs. In addition to the assigned priority, external events such as termmal mput com- 
pletion, I/O completion, and timer quantum expiration play a role in determining the effective schedulmg 
priority. 

When a job with a normal priority switches to a subprocess, the priority of the dbconnected job is reduced 
by the amount specified by the PRIVIR sysgen parameter. This causes jobs that are not connected to 
terminals to execute at a lower priority than jobs that are. Thb priority reduction does not apply to jobs 
with priorities in the fixed-high-priority group or the fixed-low-priority group. The priority reduction is .Jso 
constrained so that the priority of jobs in the normal job priority range wiU never be reduced below the 
value of (PRILOW+1). 

The following EMT can be used to set the job priority from within a program. The maximum priority which 
may be used by a job is set by the system manager. The job priority can also be set from the keyboard with 
the SET PRIORITY command. The current job priority, maximum allowed priority, and fixed-high-priority 
and fixed-low-priority boundaries may be determined with the .GVAL request. See the TSX-Plu» SyaUm 
Manager't Guide for more information on the significance of priority in job schedulmg. The form of this 
EMT is: 

EMT 37B 

with RO pointing to the following EMT argument block: 

.BYTE 0.150 
.WORD value 

where value is the priority value for the job. The valid range of priorities is to 127 (decimal). The maximum 
job priority may be restricted through the logon mechanism. If a job attempts to set its priority above its 
maximum allowed priority, its priority wUl be set to the maximum allowed. This EMT does not return any 
errors. 

Example 

See Chapter 4 for an example of the use of this EMT. 

8.11 Connecting interrupts to real-time jobs 

One of the most important uses for real-time jobs is to service interrupts for non-standard devices. TSX-Plus 
provides three mechanisms for connecting user-written real-time programs to interrupts: device handlers, 
interrupt service routines, and interrupt completion routines. Interrupt service routines and interrupt com- 
pletion routines permit jobs to process interrupts without the necessity of writing a special device handler. 
However, there are restrictions on the use of these two methods which must be considered when deciding 
the appropriate method for handling special device interrupts. 

REALTIME privilege is required to connect either interrupt service routines or interrupt completion routines 
to an interrupt vector or to release an interrupt connection. 
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The ftistest method of handling interrupts is to write a device handler (driver). Device handlers execute 
in kernel mode and provide the fastest possible response to interrupts. A device handler is the best choice 
when interrupts occur at a rate which significantly loads the system. Device handlers written for use with 
TSX-Plus should conform to the rules for writing device handlers for RT-llXM. 

The setcond method for processing real-time interrupts is to connect the interrupt to a real-time interrupt 
service routine. The interrupt service routine is written as a subroutine in a real-time job; it is not necessary 
to write a separate device handler. Interrupt service routines are connected with minimal system overhead 
and can service interrupts quite rapidly; approximately 2000 per second on an 11/44. Interrupt service 
routines are called in user mode but can only execute a limited set of system service calls (EMTs). Interrupt 
service routines can trigger the execution of interrupt completion routines to perform additional processing. 

The third method for processing real-time interrupts is to connect the interrupt to an interrupt completion 
routine. Real-time interrupt completion routines have access to the full job context and can use most 
system service calls (EMTs), but have more overhead and should not be used for interrupts that occur more 
frequently than 200 times per second. 



1S6 
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The following diagram illustrates the different levels of interrupt processing: 
Interrupt Processing 

Level 1 I Level 2 | 



Level 8 



1 



Hardware 
Interrupt 



INTEN 



J 



.FORK 



. — » 


4 




( 






Interrupt 
Service Routine 










r 








More Fork 
Requests? 


tIf.A 
















no 




4 -— 






. 




Any Pending 
Completion Routines? 


u^^ 


Interrupt Completion 
Routine 






no 









Return from 
interrupt 



This diagram shows that there are three Uvelt of interrupt processing. Level 1 is entered when a hardware 
interrupt occurs. In this level the processor (hardware) priority is set to 7 which causes other interrupt 
requests to be temporarily blocked. After some brief interrupt entry processing, the system performs a 
•FORK operation which queues a request for processing at fork level and then drops the processor priority 
to 0. At this time another hardware interrupt can occur, in which case the cycle will be repeated and another 
request for fork level processing will be placed on the queue. Note that if .FORK requests are issued at a 
sustained high rate, such that numerous prior requests cannot be serviced, a system error may eventually 
occur. 
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Level 2 processing is also known as fork level processing. This level of interrupt processing services requests 
that were placed on a queue by the .FORK operation. Hardware interrupts are enabled during this processing 
and if any other interrupts occur their .FORK requests are placed at the end of the queue. Interrupt service 
requests are processed serially in the order that the interrupts occurred. Only two system service calls 
may be used from service routines running at fork level: a request to queue a user completion routine 
for subsequent processing; and the .RSUM EMT. Fork level processing also has associated priority levels. 
Real-time processing has the highest priority. For more information on prioritised .FORK requests, see the 
TSX-Plus System Manager's Guide. 

Level 8 processing occurs in job state. That is, the TSX-Plus job execution scheduler selects the highest 
priority job or completion routine and passes execution to it. Completion routines run with full job context 
and may issue system service calls (except USR calls) as needed. Completion routines axe serialized for each 
job. That is, all other completion routines (including higher priority interrupt completion routines) which 
are scheduled for the same job are queued for execution and will not be entered until the current completion 
routine exits. During level 8 processing, interrupts are enabled and job execution may be interrupted to 
process fork level interrupt service routines or by higher priority completion routines for other jobs. 

8.11.1 Interrupt service routines 

Interrupt service routines execute in user mode but require a minimal amount of system overhead. When an 
interrupt is received through a vector which has been connected to an interrupt service routine, TSX-Plus 
executes a .INTEN and a .FORK, sets up memory management for the appropriate job, saves the status of 
the floating point unit (FPU) if it is in use, and passes control to the interrupt service routine. Using this 
approach, interrupts may be serviced at about 2000 per second on a PDP-11/44. Lower rates should be 
expected on slower processors. 
Several restrictions apply to this method of interrupt processing: 

1. The job must be locked in memory before connecting to the interrupt vector and must remain locked 
in memory as long as the interrupt connection is in effect. 

2. The processing done by the interrupt service routine should be brief since other interrupts that do 
.FORKs will be queued until the interrupt service routine exits. 

8. Only two system service calls (EMTs) are valid within a interrupt service routine: 

• A .RSUM EMT may be issued to cause the job's mainline code to continue processing if it has 
done a .SPND. 

• The TSX-Plus EMT which schedules execution of a completion routine. 

Access to the I/O page is possible if the mainline code sets up such mapping prior to the interrupt. Registers 

are undefined on entry to an interrupt service routine, and do not have to be preserved by the interrupt 

service routine. 

An interrupt service routine must exit with a RETURN instruction (RTS PC), riot an RTI. Since interrupt 

service routines execute at fork level, job scheduling is not relevant for them. All fork level processing, 

whether queued for system processing or for an interrupt service routine, is executed in the order in which the 

interrupts were received and execute before any completion routines, fixed-priority jobs or normal interactive 

time-sharing jobs. 

Use of this EMT requires REALTIME privilege. The form of the request to connect an interrupt service 

routine to a vector b: 

EMT 375 

with RO pointing to the following argument block: 
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.BYTE 20.140 

.WORD Tector-addrest 

.WORD •erTictt-70utln« 

.WORD 



where vector- addreta is the address of the interrupt vector to which the service routine is to be connected, 
and scrviee-routine is the address of the entry point of the interrupt service routine. 

The total number of vectors that can be connected either to interrupt service routines or interrupt completion 
routines is determined by the RTVECT parameter during TSX-Plus system generation. 



Error 
Code 



Meaning 



Real time not included or job not privileged 
Maximum number of vectors already in use 
Some other job is already connected to that vector 
Job is not locked in memory 



The association between an interrupt service routine and an interrupt vector may be released by the same 
EMT as used to disconnect an interrupt completion routine. See the section on releasing an interrupt 
connection later in this chapter. 

Example 



.TITLE IKTSVC 

.ENABL LC 
Dmonstratt ENT to iBplaaint an Inttrrnpt ■•rrlet roatlnt 
Slapl* flic capture progriu. 8t«al a tlaa-tharlng Una 
and pat aTarTthlng that eoaaa la on It Into a flla. 

.NCALL .TTYIN, .TTTOVT, .EXIT, .PEEI, .POIB. .OVAL, .8CCA 

.NCALL .EKTE&, .LOOKUP. .C8ISPC. .WIITE. .PUIGE. .CLOSE. .DEVICE 



VECTOI 
ICSl 

IfiVP 

BUFSIZ 

INTNBL 

CTILC 

CTILD 

SIAIT: 



6ETFIL: 
U: 



. sso 

" 176630 

> tcn*2 

* 260. 

- 100 

- S 

- 4 

.eVAL 

T8T 

BEQ 

NOV 

EKT 

NOV 

ENT 

NOV 



fA&EA.i-6. 
10 

qviT 

iLOIJOB.lO 

S76 

iKAPIO.lO 

376 

SP.8PSAVE 



Btrlal lint Ttetor 

Barial Una ICSl addrtta 

Barial Input buffar addraaa 

8iaa of bailor la vorda 

Interrupt anabla bit In ICSl 

ASCII 'C 

ASCII "D 

Soa 11 job haa 8TSP1V 

1 11 prlT, 11 not 

iBBadlato axlt 11 not prlT 

Point to ENT arg block to 

Lock Job In aaHory 

Point to ENT arg block to 

Nap PA17 into tha I/O paga 

Sara 8P prior to C8I call 



.CSISPC faUTSPC.iDEFBXT.ffO :Cat Ilia apaclllcatlon 



BCS 1( :laptat nntll Talld eoiKand Una 

NOV 8PSAVE.SP ;laatora SP. no ralld avltchaa 

.EHTEl •AlBA,iO,#INSPC.i-l ;Opan largaat poaalbla output Ilia 

BC8 1$ :0n arror, aak lor nav Ilia 

NOV f BUFFI, BITFPTl :Inltlallia bullar polntar 

CLl BLOCK ;Inltlallia output Ilia block count 

Set up to accept teralnal eonunda 

'C, *C to abort; *D to and tranaHliaion 

.SCCA «AlBA,fTTSTAI :DlBable *C abort 

NOV iACTCTD.lO ;Polnt to ENT arg block to 

ENT 976 sActlTata Input en *D 

Since we are going to borrow a currant tlae-aharlng line, we need 

to aaTe Ita rector polntera lor later reatoratlon 

NOV •ilCSl,CSlSAV ;SaTe old atataa blta, eap. Int. enable 
.DEVICE iAlEA.ffDBVLST sForce reatoratlon ol ICSl on exit 
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;Dliabl« lnt«rnipti until r«ad7 

:Gat normal Tcctor polntar 

;And aaT* It for Uttr rastorttlon 

;Ctt noraal priority 

:And saTo It for latar raatoratlon 



BIC «INTNBL.«»lCSi 

.PEEI «A&EA.iVECT01 

NOV lO.VECSAV 

.PEEI #AEEA.fVECT0t«2 

MO? 10.VECSV2 
: How attach Inttrrupt aarrica routina to Input ractor 

MOV ilHTSVC.lO jPolnt to EMT arg block to 

^^ '^^ :8ehadula Intarrupt aarvlea rontlna 

CO: BIS iINTNBL.«#acsi jEnabla Intarrupta and wait for input 

.TIYIN INBUF jWait for tarmlnal conand during tranafar 

; laauM hara whan tranafar la coaplata, or want to abort 
WHOA: — 



6(: 



BIC 

CNPB 

BNE 

.Pir&GE 

TST 

BEQ 

BK 

CNPB 

BNE 

CALL 

.CLOSE 



*INTNBL.t»ICSl 

INBUF, fCTlLC 

E$ 

«0 

TTSTAT 

GETFIL 

QUIT 

INBOF.fCTlLD 

GO 

FINISH 

#0 



iDlaabla intarrupta (data loat if Biataka) 

;¥aB it a *CT 

;Branch if not 

:If *C, throw away Input 

;Did wa gat doubla "CaT 

:If not, gat anothar flla naaa 

:If doubla *C, than abort 

;l8 tha tranaalaalon dona? 

:Braneh if not 

:Wrlta out ramaindar of currant buffar 

:If dona, eloaa out flla 



; Dona or abort, raatora tima-aharlng Una conditions 
IIUIT: NOV #EELVEC,M jPoint to ENT arg block to 

^^ '^^ :lalaaBa Intarrupt connactlon 

•POIE #AiEA,#VECT01+2.VECSV2 :laatora old priority 
•POIE iAiEA.iVECTOl.VECSAV ;And old wactor polntar 
•■S^IT ;And dona! 

Intarrupt aarrica routina. axacutaa at .FOU laral 



ISl: 



II: 



21; 



»( 



10$: 



NOVB 

INC 

CNP 

BHI 

BLO 

NOV 

Bi 

CNP 

BLO 

NOV 

NOV 

NOV 

ENT 



•«&BUF,«BUFPn 

BUFPTl 

BUFPTI,fBDFF2 

11 

9( 

#BirFFl,WITPTl 

2( 

BUFPTl. #BUFEND 

S$ 

#BUFF1. BUFPTl 

iBUFF2,VITPTI 

iSCHVlT.IO 

376 



:Put char in buffar 

:And point to naxt location 

;Vhich buffar In uaa? 

iBranch if alraady in aacond 

:laturn If flrat not full 

;Exact and of buffar 1, point to it 

;Schadula wrlta 

iSacond buffar full jatT 

;Not yat, ratum 

:Sacond buffar full, raaat polntar 

:Point to aacond buffar for wrlta 

: Point to ENT arg block to 

iSchadula coaplation routina 

;to wrlta buffar to flla 

:DoaB Bainllna want to quit? 

; Branch if not 

;If ao. diaabla intarrupta 

;Walt for anothar char 

sNota ITS PC, not ETI I 

! Coaplttion routina to aara buffar to flla 

CNPITN: .WIITB iAlEA.#0.Il.f266. .BLOCI ;Wrlta buffar to flla 



TST 
BEQ 
BIC 
lETUlN 



TTSTAT 

10$ 

*INTNBL.«#acSl 



(-C-C) 



BCC 1$ 

NOVB CTiLC. INBUF 

NOV i-1. TTSTAT 

JNP VHOA 

1$: INC BLOCK 
lETUEN 

loutiiia to coaplata wrlta of laat block 



;Br if no arror 

;0n arror. a at abort flaga 

.Skip .TTTIN. and abort 

; Point to naxt output block 



FINISH: NOV 

NOV 

CNP 

BLO 

ADD 
1$: CLIB 

CNP 

BLO 

SUB 

CALL 

EETUIN 
: ENT arg block araaa 



BUFPTl, 10 

iBUFF2.Il 

to. II 

1$ 

f2*BUFSIZ.Il 

(10)* 

10,11 

1$ 

i2*BUFSIZ,Ii 

CNPITN 



;Gat currant buffar polntar 

;Polnt to and of flrat buffar 

:Saa which buffar la uaa 

;8klp if In flrat 

:If in aacond, point to and 

:Zaro out buffar 

;A11 tha way to tha and 

;Now point back to buffar baginnlng 
;Call wrlta routina (NOT AS COMPLETION) 
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klEk: 


.BLIV 


10 


LOKJOB: 


.BYTE 


13,140 


tUPIO: 


.BTTK 


6.140 


ACTCTD: 


.BYTE 


0,162 




.VOID 


•D 




.VOID 


CTILD 


IHT8VC: 


.BTTK 


ao.i4o 




.VOID 


TECTOI 




.VOID 


ISI 




.VOID 





SCHVKT : 


.BTTK 


21.140 




.VOID 


CMPITN 




.VOID 


7 


«TPTI: 


.VOID 







.VOID 





ISLTEC: 


.BTTK 


12,140 




.VOID 


VECTOI 


; Gtntral ttorac* 


onrspc: 


.BLIV 


16. 


IN8PC: 


.BLIV 


24. 


DBFEXT: 


.VOID 


0,0,0,0 


SP8AVE: 


.VOID 





BLOa: 


.VOID 





II8IAT: 


.VOID 





VEC81¥: 


.VOID 





TBCSV2: 


.VOID 





DEn.8T: 


.VOID 


ICSI 


CS18AT: 


.VOID 







.VOID 





BUFPTl: 


.VOID 





lUBOT: 


.BYTE 


0.0,0,0 


BOFFl : 


.BLIV 


BDFSIZ 


BUFF2: 


.BLIV 


BUFSIZ 


BQFEND 







tddr) 



;G«n«r&l ENT arg block 

;EMT arg block to lock Job In bob 

;EKT arg block to up I/O pago to PAI T 

:EKT arg block to 

:8tt actiTation eharacttr 

;EICT arg block to aot up Intormpt •▼€ roatlno 

;V«ctor to attach 

jAddrooi ol Intormpt Sorrlco loutint 

;IoqTilrodi 

;EMT arg block to aehod ceapl reutino 

;Vrltt bnffor contontt to 111* 

;Ioal-tl«o prlorltx (»dda to PIIHI) 

;Paoiod In II to eoqpl rootlna (bufftr 

;Ioqalrtd 

;EHT arg block to roloaao Intorrupt connactlon 

:Vactor to bo roloatod 

;C8I output filo aptci 

:C8I input fllo opoca 

:No dtfault fllo apoco 

;8aT0 stack point or during CSI call 

; Output filo block eeuntor 

:8CCA tarwinal itatus word 

;SaTO original Toctor contontt 

; and priority 

;. DEVICE rootoration llat 

;To hold original Taluo of ICSI 

;Bnd of liot 

: Current input char pointer 

:TorBinal coaaand buffor 

;1 block input bnffor 

;8oeond buffor 



.END 



8TAIT 



8.11.2 Interrupt completion routines 

The TSX-Plus real-time support facility allows a program to connect a real-time interrupt to a completion 
routine. If this is done, TSX-Plus schedules the completion routine to be executed each tune the specified 
interrupt occurs. 

Interrupt completion routines have much greater flexibiUty than interrupt service routines, but require more 
overhead and are only capable of servicing interrupts at a lower rate. Interrupt completion routmes run 
with fuU job context. Thb allows them to use aU system service calls (except to the USR). Registers wiU be 
preserved between calls to the completion routine. 

Real-time completion routines can service interrupts at rates up to about 200 interrupts per second. Devices 
which interrupt at a faster rate should be connected through an interrupt service routme or through a special 
device handler. 

The total number of interrupt vectors that can be connected either to interrupt completion routines or 
interrupt service routines is determined by the RTVECT parameter during TSX-Plus system generation. It 
is possible for several interrupts to be connected to the same completion routine m a job but it is lUegal for 
more than one job to try to connect to the same interrupt. When an interrupt completion routme is entered, 
RO contains the address of the interrupt vector that caused the completion routine to be executed. 
Real-time completion routines, whether directly connected to an interrupt or scheduled with the EMT for 
that purpose, have an associated job priority. These arc software priorities, not hardware priorities; all 
completion routines are aynchronUed with the job and execute at hardware priority level 0. Completion 
routine priorities 1 and larger are classified as real-time priorities and are added to the system parameter 
PRIHI to yield the job execution priority, unless the resultant priority would exceed 127 in which case the 
priority will be 127. These completion routines will then be scheduled for execution whenever there are no 
executable jobs with a higher priority. 
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A real-time completion routine for one job will be suspended if an interrupt occurs which causes a higher 
priority completion routine to be queued for another job. However, a real-time completion routine for one job 
will never be interrupted by a completion routine for that same job regardless of the subsequent completion 
routine's priority. If additional requests are made to trigger the same or different completion routines while 
a completion routine is executing, the requests are queued for the job and are serviced in order based on 
their f>riority and the order in which they were queued. 

A real-time completion routine is allowed to run continuously until one of the following events occurs: 

1. the completion routine finishes execution and returns 

2. a higher priority completion routine from another job interrupts its execution — it is re-entered when 
the higher priority routine exits 

S. the completion routine enters a system wait state such as waiting for an I/O operation to complete 
or waiting for a timed interval. If a real-time completion routine enters a wait state, it returns to the 
same real-time priority when the wait condition completes. 

Real-time completion routines with a priority of are treated slightly differently than those with priorities 
greater than zero. The action taken depends on the priority of the mainline job when the completion 
routine is scheduled. If the base priority is equal to or greater than PRIHI, then the completion routine is 
treated just as those with real-time priorities greater than zero. That is, the completion routine is assigned 
a priority of PRIHI (PRIHI+the real-time priority of 0). On the other hand, if the base job priority is less 
than PRIHI, then the job is scheduled as a very high priority normal (non-interactive) job. The effect of 
this is that completion routines with a real-time priority of and a base job priority less than PRIHI will 
interrupt normal time-sharing jobs, but are time-sliced in the normal fashion and lose their high priority if 
they execute longer than the system parameter QUANlA. 

Jobs that have real-time, interrupt completion routines need not necessarily be locked in memory. If an 
interrupt occurs while the job is swapped out of memory, it is scheduled for execution like any other job and 
swapped in before the completion routine is executed. Note, however, that this condition is not optimal for 
timely servicing of interrupts. 

When a real-time interrupt occurs, a request is placed in a queue to execute the appropriate completion 
routine. If the interrupt occurs again before the completion routine is entered, another request is placed 
in the queue so the completion routine will be invoked twice. A TSX-Plus fatal system error occurs if an 
interrupt occurs and there are no free completion routine request queue entries. 

When a real-time completion routine completes its execution, it must exit by use of a RETURN instruction 
(RTS PC), not an RTI. 

Use of this EMT requires REALTIME privilege. The form of the EMT used to connect an interrupt to a 
real-time completion routine is: 



]£NT 



375 



with RO pointing to the following argument area: 

.BYTE 11,140 

.WORD interrupt-vector 

.WORD completion-routine 

.WORD priority 

where inUrrupt-vector is the address of the interrupt vector, completion- routine is the address of the com- 
pletion routine, and priority is the execution priority for the completion routine. 



Error 
Code 



Meaning 



Real-time support not included or job not privileged 
Majcimum number of vectors already in use 
Some other job is already connected to that vector 
Job is not locked in memory 
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Example 



.TIILK AITVEC 

.EHiBL LC . . * 

DnoMtrat* TSX-PIm KKT. Ip attach a eomplatioii roatin* to an Inttrmpt 



CTILC 

EllBTT 

ICSl 

IBUF 
IKTNBL 

STilT: 



• 8 
. 52 

■ 1T6540 

■ 1CSI^2 
> 100 

.NCALL 

HOT 

ENT 

BCC 

.niHT 

.EXIT 



;8arlal Una ICSl addraaa 

;Lina input bnffar addraaa 
:Intarnipt anabla bit In ICSl 
.PUNT . .EXIT , .IITOUI . .SPHD . .ISOM 
iMlPIOP.lO ;Point to EHT arg block to 
376 :Nap to I/O paga 

1$ : Branch if OK to up 

#N0P1IT :Toa ara not allovad to do that 



+ 

If thlB Job wara to ba raaldant for a long tl«a. it would bo battar 
to lock into low BaBory to aToid ■omory fragmantatlon by Job awapplng. 
iowoTar. alnea thlo Job Bay hara to ba awappad now to gat Into low 
■anory, locking into low maaory takaa longar to axacnta. 

Ij. NOT iLOILOW.lO ;Polnt to EHT arg block to lock into low bob. 

1$: NOV •LOKJOB.IO :Point to ENT arg block to 

;Lock tha Job in BOBory 
;Polnt to EHT arg block to 
; Attach to an Intarnipt Toctor 
;Contlnaa if OE 

;lIotlfy cannot attach to intarmpt 
;Plnd ont which arror 
;ConTart to word offaat 
:And asqtlaln raaaon for arror 
;0o on to unlock and axit 

2$: .PlIHT #TYPB jProBpt for Input froB intarrupting darLca 

;Enabla Input intarmpt a 
;Now wait for an Intarrupt 

'.laauna hara on axit froB craplation coda 
;Point to EHT arg block to 
:lalaa8a an intarrupt ractor 

NOTE: Any intarrupta through thlo TOctor aftar it haa baan ralaaaad 
will eanaa a T8X— Plua fatal ayatoB arror - Unaxpactad Intarrupt. 



NOT 


iLOXLOV.lO 


NOT 


•LOKJOB.IO 


ENT 


976 


NOT 


•ATTTEC.IO 


ENT 


376 


BCC 


2( 


.PUNT 


tBADATT 


NOTB 


•iRUBTT.lO 


A8L 


10 


.PUNT 


ATTEll(lO) 


BE 


9$ 


.PlIHT 


#TYPE 


BIS 


•INTNBL.tilCSl 


.SPND 




NOT 


fflELVEC.lO 


ENT 


976 



9$: 



NOT 
ENT 
.EXIT 



iUNLOXJ.lO :Point to ENT arg block to 
376 :Onlock thla Job froB BCBory 



Tha following coda will bu axacutad aa a coiqilatlon rontlna 
whan tha darlea attachad %o tha ractor intarrupta. 



CNPITN: 


NOTB 


•ilBUr.lO 




CNPB 


10, f CTILC 




BEq 


11 




.TTTO0T 






NOT 


•SETPII.IO 




ENT 


376 


, . . . 


CLE 


PlILET 




NOT 


tSETPlI.lO 




ENT 


976 




Bl 


2$ 


!•: 


.18UN 




21: 


lETOlM 




HAPIOP: 


.BYTE 


6,140 



:Bntar hara whan naw charaetar la aTullabla 

:Gat tha naw charaetar 

{Should wa qnltT 

;quit on *C 

;DiBplay tha charaetar 

;Point to EHT arg block to 

;8at procoBBor priority (block intarrupta) 

;TiBa critical procaoaing goaa hara 

;8at priority back down 

{Point to EHT arg block to 

:Sat procaaaor priority (ra-anabla intarrupta) 

ilatum to Bainlina coda 

:Valt for naxt intarrupt (NOTE: Mot ITI) 

;ENT arg block to Bap to I/O paga 
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14S 



LOILOW 


.BTTH 


LOIJOB 


.BYTE 


DHLOKJ 


.BTTB 


ATTVEC 


.BYTE 




.WO&D 




.WOID 




.VOID 


KRI.VBC 


.BYTE 




.¥0&0 


SSTPII 


.BYTE 


PIILEV 


.¥OID 


ATTEU 


.VOEO 




.VOLD 




.WOED 




.NLIST 


rrPE: 


.ASCIZ 


BADATT 


: .ASCIZ 


NOPEIV 


: .ASCII 




.ASCIZ 


NAXINT 


: .ASCIZ 


IND8E: 


.ASCIZ 




.END 



7,140 

13.140 

10.140 

11.140 

340 

CKPKTN 

7 

13.140 

340 

16.140 

7 

NOPIIT 

NAXINT 

INUSE 

BEX 

/Characttri •nterad on lerial lint will bt dlaplaycd hart:/ 

/TATTVEC-F-Caimot attach to lntarnipt./<7> 

/laal-tlBo aupport not aptelfitd during TSGEN or / 

/uatr not prlvllogad./ 

/NasdBiu nuabar of intarrupta alraady in uaa./ 

/Anothar job alraady connaetad to intarrupt./ 

8TAIT 



;ENT arg block to lock job into low mm. 
;ENT arg block to lock job in placa 
;ENT arg block to nnloek job froa aoaorj 
;BMT arg block to attach to intarrupt 
; Intarrupt ractor 
sAddraaa of eoaplation routlna 
;Iaal-tiaa priority (NOT procaaaor priority!) 
;ENT arg block to ralaaaa intarrupt ractor 
; Intarrupt Tactor 

:ENT arg block to aat procaaaor priority 
;Daairad priority laval (aodifiabla) 
: Attach to intarrupt arror tabla 



8.12 Releasing an interrupt connection 

A connection between an interrupt vector and an interrupt service routine or an interrupt completion routine 
remains in effect until the job exits or the following EMT is executed to release the connection. Use of this 
EMT irequires REALTIME privilege. 

Warning: An interrupt through a vector which has been released with this EMT or which was connected to 
a job that has terminated will cause a fatal system error: "UEI-Interrupt occurred at unexpected location" . 
This can be circumvented by including the vector in a .DEVICE list. 

The form of the EMT is: 

ISMT 375 

with R:0 pointing to the following argument area: 

BYTE 12.140 
.WORD interrupt-vector 

where interrupt- vector is the address of the interrupt vector whose connection is to be released. 

Example 

See th(E example program ATTVEC in section 8.11,2 on connecting a real-time interrupt to a completion 
routine. 

8.13 Scheduling a completion routine 

Real-time programs may schedule a completion routine for execution with a special EMT provided for that 
purpose. This is particularly valuable from within interrupt service routines which do not have access to 
system service calls other than this EMT and the .RSUM request. The primary intent of this request is 
to provide a mechanism for access to system service calls from interrupt service routines. The form of this 
EMT is: 



ENT 



375 
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with RO pointing to the following argument block: 



BYTE 


21.140 


WORD 


completion-routine 


WORD 


priority 


WORD 


Rl-ralue 


WORD 






where completion-routine is the address of the entry point of the completion routine that is being started, 

priority is the real-time priority level for the completion routine being started, and Rl-value is a value to 

be placed in Rl on entry to the completion routine. 

Completion routines scheduled in this manner follow the same rules as for interrupt completion routines 

described above, except that they are scheduled as a result of the EMT call rather than in response to an 

interrupt. 

Example 

See the example program INTSVC in section 8.11.1 on connecting interrupts to real-time jobs with interrupt 
service routines. 

8.14 Adapting real-time programs to TSX-Plus 

The following points should be kept in mind when converting an RT-11 real-time program for use under 
TSX-Plus. 

• The I/O page (160000-177777) is not directly accessible to the program unless the program executes 
the TSX-Plus real-time EMT that maps the job's virtual region to the I/O page or is started with the 
/lOPAGE switch to the R[UN] command. 

• If the program's virtual region 160000 to 177777 is mapped to the I/O page, the program must use 
.GVAL to access offsets in the simulated RMON. 

• Since FORTRAN uses PAR 7 to map to virtual arrays, if both direct I/O page access and FORTRAN 
virtual arrays are required in the same program, then some PAR other than 7 must be used to map 
to the I/O page. 

• Real-time interrupts are connected to interrupt service routines and interrupt completion routines 
by use of the TSX-Plus real-time EMT for that purpose. The program should not try to connect 
interrupts by storing into the interrupt vector cells. 

• The .PROTECT EMT is ignored under TSX-Plus and always returns with the carry flag cleared. 

• Interrupt service routines and completion routines connected to real-time interrupts should exit by use 
of a RTS PC instruction rather than RTI. 

• Programs that require very rapid response to interrupts should use the interrupt service routine method 
and must lock themselves in memory. 

• Real-time interrupts must not occur unless an interrupt service routine or completion routine is con- 
nected to the interrupt. If a real-time interrupt occurs with no associated interrupt service or comple- 
tion routine, a fatal TSX-Plus system error (UEI) occurs and the argument value displays the address 
of the vector of the interrupt. 

• A higher priority real-time completion routine for one job will interrupt a lower priority completion 
routine being executed by another job but will not interrupt a lower priority completion routine being 
executed by the same job. 

• A real-time completion routine running at priority 1 or above is not time-sliced and will lock out all 
lower priority jobs until it completes its processing or enters a wait state. 



Chapter 9 

Shared Run-time System Support 



TSX-Plus provides a faciUty that allows one or more shared run-time systems or data areas to be mapped 
mto the address space of multiple TSX-Plus time-sharing jobs. There are two primary uses of this facility: 

• Memory space can be saved by having multiple jobs that use the same run-time system access a 
common copy rather than having to allocate space within each job for a copy. 

• ^'V'.^r''^^ ^'^ communicate with each other through the use of a common shared memory region to 
which all of the communicating jobs have direct access. 

To use this facility, information about all of the shared run-time systems must be declared when the TSX- 
Plus system is generated. During system initialization the shared run-time system files are opened and read 
mto memory. These shared run-time systems remain in memory as long as the system is running and are 
never swapped out of memory even if there are no jobs actively using them. 

The EMTs described below can be used to associate one or more shared run-time systems with a job When 
such an association is made, a portion of the job's virtual memory space is mapped to allow access to part 
or all of one or more run-time systems. 

9.1 Associating a run-time system with a job 

The following EMT is used to associate a shared run-time system with a job. The form of the EMT is: 

EKT 375 

with RO pointing to the following argument area: 

•BYTE 0.143 

.WORD name-pointar 

where name-pointcr is the address of a two word cell containing the six character name of the shared run-time 

whlrTSY PI . TZ ^^"•^''P^"^'' *° ^^' fil« ^*"^« ^l^i<^h was specified for the run-time system 

when TSX-Plus was generated. If the name pointer value is zero, the effect of the EMT is to disassociate 
a 1 shared run-time systems from the job and to re-establish normal memory mapping for the job N^Ie thai 
disassociatmg shared run-time systems in this manner also dbassociates any ex^Lg ''ral! W tapp^ng^^^ 

litv2^::zzt:fT''^' "^ '''"'''' ^^^^ ^'^ '^''^ ^ ^^^^ '^^^«'^^-^' ^^^ ^-^ ^^^^ ^ -^ - 

The effect of this EMT is to associate a particular shared run-time system with the job. However this EMT 
does not affect the memory mapping for the job or make the run-time system visible t~;b;thaf^ 
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done by the EMT described below. If some other run-time system has been previously mapped mto the 
job's region, that mapping is unaffected by this EMT. Thus it b possible to have multiple run-time systems 
mapped into the job's region by associating and mapping them one at a time into different regions of the 
job's virtual memory space. 



Example 



.TITLE 
.ENABL 
; Dnionitratlon 
.NCALL 



Pill 

STAIT: NOT 

ENT 



aoooo 



i(: 



31: 



BCC 

.PUNT 

.EXIT 

MOT 

ENT 

CALL 

CLI 
NOT 
ENT 



.EXIT 
USE&TS: .BITE 
.VOID 
.1A060 
.BYTE 
.WOIO 
.WOtO 
.VOKD 
.MIIST 
N08KET: .ASCIZ 
.END 



USE1T8 

LC 

ol T8X— PluB ENT tp up to & thaTAd ruii-tl«« rtgion 

.PiINT,.EXIT 

;Bat* addrtai of PAl 1 window 
fUSE£TS.10 ; Point to ENT arg block to 
376 ;Ai«oelato a aharod rua-tlma roglon 

1| ;ErrorT 

♦NOSHiT ; Can't find naaod aharad run-tl«a 

iNAPRTS.lO ;Polnt to ENT arg block to 
3TB ;Nap to ahartd nm-tlmt ayattm 

•i<PA&l-»200> :JSl to antry point In aharod region 

; which prlnta aoma data froa that*. 
<DSEaTS+2> jUndaclara any aharod mn-tl«oB 
iUSEETS.lO ;Polnt to ENT arg block to 
376 :DlBBoclato all aharad raglona 

;6o on with othar procaaalng 



SKIN AN 
NAPITS 



;ENT arg block to aaaoclata 

-.Polntar to flla naaa 

:8harad raglon flla naaa 

:BNT arg block to aap aharad raglon 

:Nap PAE 1 

:OffBat into raglon 

:81ia of raglon (64. byta blocka) 



0,143 

8HENAN 

/ITCON / 

1,143 

1 



1000/64 . 

BEX 

/Can't find tha aharod run-tl«a ByataB./<7> 

8TA&T 



The example program RTCOM declared in the above program was defined during TSX-Plus system gener- 
ation with the RTDEF macro as follows: 

RTDEF <SY RTCOM SAV>,RVr,l 
and the shared program itself was: 



.TITLE ITCON 

.ENABL LC 
SoaonBtratlon aharod ran-tlaa 
(Poaltlon Indopandent Coda.) 



flla 



8TA1T: 



ENTIT: 



.NCALL .PilNT 

.NLI8T BEX 

.PSBCT ITCON, I :1TDEF in T8GEN apaclfloa 

:aklp 1 block ao default atart addrooa of 1000 la OX 

.A8CII /Thla data waa produead by tha / 

.ASCIZ /ITCON aharad mn-tlaa raglon./ 



. ■ 8TUT * aoo 

NOT PC, 10 

8DB f<.-STAIT>,IO 

.PUNT 10 

lETDIN 

.END ENTIY 



;Entry point for aharad coda 
;Flnd ont whara wa ara 
; Point back to data araa 
;Dl8play what la thara 
:And go back to MAIN 
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9.2 Mapping a run-time system into a job's region 

Once a shared run-time system has been associated with a job by use of the previous EMT, the run-time 
system (or a portion thereof) can be made visible to the job by mapping it into the job's virtual address 
region. The form of the EMT to do this is: 



IBNT 



375 



with RO pointing to the following argument area: 



.BYTE 1,143 

.WORD par-region 

.WORD run-time-off set 

.WORD mapped- size 



The par-region parameter is a number in the range to 7 that indicates the Page Address Register (PAR) 
that isi to be used to access the run-time system. The PAR number selects the region of virtual memory 
m the job that will be mapped to the run-time system. The following correspondence exists between PAR 
numbers and virtual address regions within the job: 



PAR 


Address Range 





000000-017777 


1 


020000-037777 


2 


040000-057777 


3 


060000-077777 


4 


100000-117777 


5 


120000-137777 


6 


140000-157777 


7 


160000-177777 



The run-Umt-offtet parameter specifies which portion of the run-time system is to be mapped into the PAR 
region. The run-ttme-offett specifies the number of the 64-byte block within the run-time system where the 
mapping is to begin. This makes it possible to access different sections of a run-time system at different 
times or through different regions. 

The mapped-size parameter specifies the number of 64-byte blocks to be mapped. If this value is larger than 
can be contamed within a single PAR region, multiple PAR regions are automaticaUy mapped as necessary 
to contain the entire specified section of the run-time. 

If an error is detected during execution of the EMT, the carry-flag is set on return with an error code of 1 
to indicate that there is no run-time system associated with the job. 

This EMT only affects the mapping of the PAR region specified in the argument block (and following PARs 
If the size so requires). It does not affect the mapping of any other PAR regions that may previously have 
been mapped to a run-time system. Thus a job may have different PAR regions mapped to different sections 
of the same run-time system or to different run-times. Real-time programs may map PAR 7 to the I/O paee 
and also map other PAR regions to shared run-time systems. 

The memory size of a job is not affected by the use of the shared run-time control EMTs. That is, mapping 
a portion of a job s virtual address space to a shared run-time system neither increases nor decreases the 
size of memory occupied by the job. If a job's size is such that a portion of its normal memory is under a 
PAR region that is mapped to a run-time system, that section of its normal memory becomes inaccessible 
to the job as long a^ the run-time system mapping is in effect, but the memory contents are not lost and 
may be re-accessed by disassociating all run-time systems from the job. 

Note that any of the PAR regions may be mapped to a run-time system including PAR 7 (160000-177777). 

Example 

See the example program USERTS in section 9.1 on associating a run-time system with a job. 
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9.3 Fast mapping to shared run-time regions 

The foUowing EMT allows a program to define a set of "regions" in one or more shared run-time systems. 
The form of the EMT is: 

EMT 375 

with RO pointing to the following argument area: 

.BYTE 2,143 

.WORD par-number 

.WORD offset 

.WORD size 

.WORD region-number 

Up to 40 regions can be defined by each job. The TRAP instruction M^^'^*^*^"; ^MT) b then used to 
cause a selected region to be mapped into the virtual address range of the job. The TRAP mstruction is 
uted to IvoTd the overhead involved in general EMT processing. This method of mapping shared run-tunes 
is approximately 10 times as fast as the method using EMT function 148, subfunction 1. 
A region can be redefined to perform different mappings at different times but most commonly a set of 
regions is defined during program initialization and then the TRAP instruction is used to select the region 
that b to be mapped as the program executes. The following information is required to define a region: 

1 The region index. This is a number in the range to 59 that identifies the region. This index number 
is later used with the TRAP instruction to select the region being mapped. 

2 The number of the Page Address Register (PAR) through which the region is to be mapped PAR 
numbers are in the range to 7 and each PAR can map up to 8 Kb. One region " "J^PP^^^ /^^ jf 
one PAR (i.e., a region cannot span PAR's). Different regions can be mapped through different PAR s. 

8. The size of the region. The size is specified in 64-byte units. Up to a full PAR (8 Kb) can be mapped 
through a region. 

4. The shared run-time system that is being accessed through the region. 

5. The offset (in 64-byte blocks) from the beginning of the shared run-time system where the mapping is 
to begin. 

This EMT can return the following error codes: 



Code 



Meaning ; 

No shared run-time has been associated with job 
Region number is invalid 

Specified size is greater than 128 units of 64-byte8 (8 Kb) 
Specified offset is beyond the end of the run-time 



The following sequence of operations must be performed to define and map regions: 

1 Associate a shared run-time system with the job by use of the EMT with function code 148, subfunction 
(see shared run-time chapter of the TSX-Plu* Rafcrcnec Manual). Thb does not cause any portion 
of the run-time to be mapped into the job's address space but simply specifies which run-time is bemg 
referenced by subsequent EMT's. 

2. Use the new EMT with function code 148, subfunction 2, to define the regions of the run-time. This 
simply defines the characteristics of the regions, it does not cause them to be mapped into the job's 
address space. You may define regions in different shared run-times by associating a different run-time 
before you use the define-region EMT. 
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S. When you are ready to map a region into the job's address space, load RO with the region number you 
specified when you defined the region, and execute a "TRAP 1" instruction. The carry flag will be 
cleared following TRAP if the mapping was successful. Carry flag being set indicates that an invalid 
region number was specified in RO. 

If any run-time regions have been defined by the job, the TRAP instruction is dedicated for use in region 
mapping. If there are no defined run-time regions, the TRAP instruction can be used for other purposes as 
before. All run-time region definitions are cleared when a program exits or chains. In addition, the following 
EMT can be used to clear all run- time regions and return the TRAP instruction to its normal function: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 3.143 
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Chapter 10 

Program Debugger 



Programming errors can sometimes be very difficult to identify and correct without a detailed stepwise 
examination of a program's progress. Some higher level languages, like COBOL-Plus, include a debugging 
tool that allows such examination. For programs written in MACRO assembly language or when it is 
desirable to examine a program at the level of individual instructions, TSX-Plus provides a debugging 
facility with the following features: 

• The debugger is included as an optional system overlay and does not share memory space with the 
program being debugged. This allows programs up to the full 64 Kb virtual address space to be run 
with the debugger. It can also be used with programs which are mapped to the I/O page or which 
use overlays, shared run-time systems, or extended memory regions (PLAS regions; virtual arrays or 
overlays). 

• The debugger does not have to be linked with the program being debugged. It can be invoked when 
the program is executed by the RUN/DEBUG command. 

• A keyboard command can be issued to permit debugging of any subsequent user program or utility 
even if the program is not started with the RUN/DEBUG command. 

• Execution of a program can be interrupted at any time by typing CTRL-D. This causes entry to the 
debugger similar to hitting a breakpoint in the program. 

• The debugger can decode instructions into symbolic assembly language. 

• Program traps to 4 and 10 are caught by the debugger rather than causing a program abort with 
return to the keyboard monitor, unless the program has issued a .TRPSET EMT. 

• A data watehpoint facility is included which can cause an execution break to occur when the value of 
a monitored data item is changed. 

10.1 Debugger requirements 

In order to make effective use of the debugger facility, it is necessary to have a link map of the program 
bemg debugged. This minimizes the usefulness of the debugger for interpreted languages (e.g., BASIC) 
and languages with a run-time system (e.g., DIBOL) unless one is interested in debugging the'run-time 
mterpreter. For other high-level languages (e.g., FORTRAN and Pascal) the debugger is most useful for 
small program sections for which the intermediate assembly code is available. 

The debugger facility is an optional feature of TSX-Plus, included during system generation. Debugger 
support must have been selected during system generation (DBGFLG=1) in order to use this feature. 
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Id/ 

10.2 Invoking the debugger 

The debugger need not be linked with the program being debugged. Programs may either be started under 
debugger control with the RUN/DEBUG command, or can be interrupted while runnmg by typmg CTRL-U 
if the SET CTRLD DEBUG command has been previously bsued. 

10.2.1 RUN/DEBUG switch 

A program may be started under control of the debugger with the /DEBUG switch to the RUN command. 
For example: 

RUN/DEBUG PRGNAM 

When a program is started under debugger control, the program is loaded and the debugger prompt appears. 
For example: 

RUN/DEBUG PRGNAN 
TSX-Plus debugger 
DBG: 

Whenever the debugger is in control, the DBG: prompt will appear and the debugger will be ready to accept 
a command. 

On entry to the debugger, the program start address is loaded into RO and set so that program execution 
may be initiated with the -jG" command without specifying a starting address. It is usually desirable to set 
initial values for relocation registers and breakpoints before starting program execution. 

10.2.2 CTRL-D Break 

CTRL-D normally only interrupts program execution if the program has been started by the 
RUN/DEBUG command. However, a keyboard command is available to enable CTRL-D to interrupt a 
program and pass control to the debugger even if the program was not started under debugger control. 
See the description of the SET CTRLD DEBUG command in the TSX-Plus U$er'$ Reference Manual. If 
CTRL-D interruption has been enabled, then any program may be interrupted and control transferred to 
the debugger regardless of whether the program was started under debugger control. The effect is similar to 
hitting a breakpoint at the current location. The same debugger commands and facilities are available when 
the debugger is entered this way as when the program is started under debugger control. Note however, 
that if the SET CTRLD DEBUG command has not been issued prior to starting a program's execution 
and that program is not started with the RUN/DEBUG command, then CTRL-D will have no special 
effect on the program and debugger control cannot be obtained without restarting the program. The SET 
CTRLD DEBUG command is local to each time-sharing line and must be invoked from that line to enable 
CTRL-D breakpoints in programs which are not started with the RUN/DEBUG command. If a program is 
started with the RUN/DEBUG command, then CTRL-D may be used to interrupt its execution regardless 
of whether the SET CTRLD DEBUG command has been issued. 

See the Special Notes section at the end of this appendix for information about interactions of CTRL-D 
with special terminal mode and special activation characters. 

10.3 BPT Instruction 

A program which includes a BPT instruction can trigger execution of the system debugger. If a BPT 
instruction is executed by a program which is not currently associated with the system debugger and location 
14 (trap vector for BPT) in the program is zero (0), then the system debugger is entered with the instruction 
that follows the BPT as the current instruction. If a program is already associated with the system debugger 
(RUN/DEBUG or by a CTRL-D) when the BPT is executed, then the BPT does not cause entry to the 
debugger. 
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10.4 Commands 

The commands and syntax of the debugging facility are similar to those of RT-U's ODT. However, not all 
ODT commands are implemented and some additional features are provided. In the following list of debugger 
commands, angle brackets are used to indicate special terminal keys such as <RETURN>, <TAB> and 
<LINE FEED>. The angle brackets are not part of debugger command syntax. Many commands accept a 
numerical value or address, indicated here as value, addreee, repeat or n. The underlined portion should be 
substituted with the appropriate number when issuing the command. The value is optional in some cases. 
All numerical values are assumed to be octal unless terminated by a decimal point. The period character 
(".") may be used to indicate the current value of the program counter; for example, see the address ;nB 
command to set an instruction breakpoint. 



Debtigjger Commands 



Command 



addrettj 



addreet\ 



vo/uc <RETURN> 



value<UNE FEED> 



Meaning 



Display the contents of the addressed word. 



Display the contents of the addressed byte. 



Store value into the currently open cell. If value is omitted, close the current 
location without changing its contents. 



t/fli/uc" 



<BACKSPACE> 



(underscore) 



address] 



address] 



value<TAB> 



Store value into the currently open cell and then advance to the next word 
or byte. If value is omitted, advance to the next location without changing 
the value of the current location. 



Store value into the currently open cell and then advance to the previous 
word or byte. If value is omitted, back up to the previous location without 
changing the contents of the current location. 



Equivalent to up- arrow (**""). 



Open the cell whose address is specified by the contents of the currently 
open cell. 



Open the cell whose address is specified by the contents of the currently 
open cell plus the current location plus 2. 



Open the cell whose address b specified and display its contents as a sym- 
bolic instruction. If address is omitted, decode the contents of the currently 
open cell into symbolic instruction form. 



Open the cell whose address is specified and display its contents as a sym- 
bolic instruction. If address is omitted and a cell is currently open as an 
instruction, close the current cell and open the next cell and display its con- 
tents in symbolic instruction format. The location of the next cell opened is 
determined by the number of words used by the instruction in the currently 
open cell. 



Execute the next instruction in single step mode. It is not necessary to issue 
the "ilS" command to single step using the TAB key. If value is non-blank, 
the value is used to calculate the address of the next instruction to be single 
stepped (similar to "jlS", then value;P). If zero (0) is substituted for value 
before <TAB> is typed and the next instruction is a JSR (CALL), then a 
temporary breakpoint is set beyond the JSR to catch the return from the 
called subroutine and the subroutine is executed without single stepping. 
This can be used to avoid single stepping through subroutines called from 
code that is being single stepped. 



154 



CHAPTER 10. PROGRAM DEBUGGER 



Command 



addree$,nR 



nR 



addrcet;nB 



address ,0 



repeat;P 



;nS 



addrest',valueM 



Meaning 



Set relocation base register n to address. There are 8 relocation registers, 
numbered through 7, 



Convert the contents of the currently open cell into an oflFset relative to 
relocation register n. 



Convert the current address to an offset relative to relocation register n. 



Set an instruction breakpoint at address. There are 8 instruction break- 
points, numbered through 7. To clear a breakpoint, substitute for 
address. The period character may be used to indicate the current value 
of the program counter. For example, to set breakpoint 1 at the current 
address: 



:1B 



Go to location address and start program execution there. 



Proceed from a breakpoint. If repeat is non-blank, do not break again until 
repeat breakpoints have been hit. If repeat is omitted, proceed until the 
next breakpoint is hit. 



Set or reset single stepping mode. If n is l^(or any other non-zero value), 
begin single step mode. When single stepping, execution will proceed one 
instruction for each execution of the ";?" command. If n is or is omitted, 
single stepping mode is cancelled and the program will resume normal exe- 
cution when the ";?" command is issued. (See also the <TAB> command.) 



Interpret the contents of the currently open word as a RAD50 value and 
display it as a three character ASCII string. Up to three characters may 
be entered after the current value is displayed. The new characters will 
be converted to a RAD50 value and stored in the current location. Any 
characters beyond the first three are ignored. 



Set a data watchpoint. The word specified by address is monitored. If value 
is specified, a data watchpoint occurs when the value of the word matches 
value. It is possible to watch only selected bits of the monitored address by 
setting the mask register (see $M and data watchpoint description below). 
If value is omitted, a data watchpoint occurs any time the value of the word 
changes. 



10.5 CTRL-D breakpoints 

When a program has been started by the RUN/DEBUG command, its execution can be interrupted at any 
time by typing CTRL-D. (If the SET CTRLD DEBUG command has been issued, then the program need 
not have been started under debugger control.) Typing CTRL-D causes the program to stop as though 
a breakpoint had been encountered at the current location and passes control to the debugger. Any valid 
debugger command may be issued at this point, and program execution may be resumed with the **;?" 
command. If a system service call (EMT) is being executed when CTRL-D is typed, the service call will 
run to completion and control will be passed to the debugger at the point of return to the program from the 
EMT. 

See the Special Notes section at the end of this appendix for more information on interactions of CTRL-D 
with special terminal mode and special activation characters. 



10.6. ADDRESS RELOCATION 

10.6 Address relocation 
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Address values in commands may be specified absolutely or in the form n, off$et, where n is a relocation 
register number and offset is the offset relative to that relocation register. 

When an instruction is decoded into symbolic form, relative addresses are displayed in the form [n,offtct] 
as an offset from the nearest relocation register whose value is lower than the address. The format register 
($F) can be used to control the display format of addresses. 

Only two bits are significant in the $F register, bits and 1. Bit controls the display of instruction address 
operands, and bit 1 controls the display of location values. Setting either bit causes the corresponding 
addresses to be displayed in absolute format. Clearing either bit causes the corresponding addresses to be 
displayed in relative format. Both default to relative format ($F=0). 

Address Display Format 



$F 


Locations 


Operands 



1 
2 
S 


relative 
relative 
absolute 
absolute 


relative 
absolute 
relative 
absolute 



10.7 Internal registers 

The following special address symbols axe used to specify machine registers: 




Registers RO through R5 
Register 6, the stack pointer (SP) 
Register 7, the program counter (PC) 
Processor Status Word 



The following special address symbols are used to specify internal debugger registers: 



$M 
$F 
$B 
$R 



Mask register, used with data watchpoints (see below) 
Print format control register (see above) 
Start of instruction breakpoint address registers 
Start of relocation registers 



10.8 Data w^atchpoints 

The data watchpoint facility is a powerful tool for determining where a particular data cell is being modified. 
The form of the command used to initiate a watchpoint is: 

address; valueN 

where address is the address of the word that is to be monitored, and value is an optional parameter that 
specifies a value to be watched for. If value is omitted, a data watchpoint occurs any time the value of the 
word changes. If value is specified, a watchpoint only occurs when the value of the word matches the specified 
value. When a watchpoint occurs, the program counter is pointing past the instruction which modified the 
word. 

A data mask may be specified to select a portion of the word being monitored with the watchpoint. The 
mask value may be referenced using the register name "SM". Initially the value of the mask is 177777 which 
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causes the entire word contents to be monitored. If some other value is stored in $M, only the bits selected 
by the mask oxe monitored. 

Use of the data watchpoint facility causes the program to execute very slowly. When a watchpoint is in effect 
the debugger causes a break to occur on each instruction executed and then checks to see if the monitored 
data word has changed value. If a watchpoint b in effect but no instruction breakpoints are set, the execution 
of the program is slowed down by a factor of about 55 (i.e., the program takes 55 times as long to execute). 
If a watchpoint is in effect and instruction breakpoints are also set, the speed reduction factor is about 80. 
There is no significant speed reduction when instruction breakpoints are set but no watchpoint is in effect. 
The best strategy is to set an instruction breakpoint as close as possible to the code which is modifying 
the data word and then, when that breakpoint is reached, remove the instruction breakpoint, set the data 
watchpoint, and proceed with execution. 

10.9 Symbolic instruction decoding 

Symbolic instruction decoding is used to interpret values according to their numerical op codes and convert 
them into symbolic zissembly language format. The display format of address operands is controlled by the 
$F register. When a breakpoint is reached, the instruction on which the breakpoint was set is displayed in 
its symbolic form. Specific locations can also be symbolically decoded with the **[" and **]" operators. 

The "(" command can be issued to symbolically decode a value which has just been displayed using the "/" 
command or to symbolically decode the contents of a specific location. The following examples illustrate 
how thb might be done (the commands typed by the user are italicized): 

am. 2030/ 010246 / MOV R2,-(SP) DBG iSOOOf BIT #2000, [3. 100] 

The "]" operator closes the currently open cell, opens the next cell and displays its contents in symbolic 
instruction form. The number of words to skip from the currently open cell to the next cell is determined by 
the number of words used by the instruction in the currently open cell. Thus, the **]" operator is convenient 
for examining a consecutive set of instructions. 

10.10 Special notes 

Address location is special to the debugger. For example, symbolic instruction decoding is not done for 
address 0, and line-feed does not step to the next location after examining location 0. 

Since CTRL-D is used by the debugger to dynamically interrupt a program, CTRL-D will not be passed 
through to a running program even if the program is in special terminal input mode (TTSPC$ bit set in 
the JSW). If the program is waiting for terminal input when CTRL-D is typed, then it is necessary to type 
an activation character (usually <RETURN>) before causing a break to occur and passing control to the 
debugger. 

If a program declares CTRL-D as a special activation character, then CTRL-D is always passed to the 
program and cannot be used to cause a break in that program and pass control to the debugger. 

When the debugger is operating in single step mode, normal breakpoints are temporarily removed and are 
restored when leaving single step mode. A side effect of this is that if the program executes an instruction 
(such as RTT) which clears the T (trace) bit in the processor status word, then single stepping is lost, 
breakpoints are not restored and the program continues execution. 

Breakpoints set in overlay regions are only valid while that overlay is resident. If another overlay becomes 
resident, any breakpoints set in the previous overlay are lost and must be reset. 

An attempt to set a break-point in a shared run-time region which is mapped as read-only will result in the 
error: 

?MON-F-K©rnel mod« trap within TSX-Plu« 
Abort location " xxxxxx 



10.10. SPECIAL NOTES j57 

When examining the processor status word ($S register), keep in mind that only the low 4 bits (condition 
codes) are significant to the program. The trace bit is used by the debugger. The priority bits are not 
significant in user mode under TSX-Plus. And, the high 4 bits will always be set, indicating user as both 
previous and current mode. 

If the user program has issued a .TRPSET call, then traps to 4 and 10 are not intercepted by the debugger, 
but a:re passed to the user program's trap handling routine. 
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Chapter 11 

TSX— Plus Performance Monitor 
Feature 



TSX-Plus includes a performance analysis facility that can be used to monitor the execution of a program 
and determine what percentage of the run time is spent at various locations within the program. During 
performance analysis, TSX-Plus examines the program being monitored when each clock tick occurs (50 or 
60 times per second) and notes at what location in the program execution is taking place. Once the analysis 
is completed the TSX-Plus performance reporting program (TSXPM) can be used to produce a histogram 
showing the percentage of time spent at various locations during the monitored run. 

There axe three steps involved in performing a performance analysis on a program: 

1. Use the MONITOR command to begin the analysis. 

2. Run the program to be monitored. 

3. Run the TSXPM program to print a histogram of the result. 



11.1 Starting a performance analysis 

The first step in doing a performance analysis is to use the MONITOR keyboard command to tell TSX-Plus 
that a performance analysis is to be done on the program that will be run next. The form of the MONITOR 
command is: 

MONITOR base- address . top-address [ . cell-size] /switches 

where base-address is the lowest address in the region to be monitored, top-address is the highest address 
in the region to be monitored, and cell-size is an optional parameter that specifies the number of bytes of 
address in the region being monitored to be grouped together into each histogram cell. If cell-size is not 
specified, TSX-Plus calculates the cell size by dividing the number of bytes in the region being monitored 
(base-address to top-address) by the total number of histogram cells available (specified when TSX-Plus is 
generated). This gives the finest resolution possible. The only available switch is /lO which causes I/O wait 
time to be included in the analysis. If this switch is not specified, only CPU execution time is included in 
the analysis. A link map of the program should be available to determine the addresses in the program that 
are appropriate to monitor. 

Examples 
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MONITOR 1000.13000/10 
MONITOR 20000.40000,10 
MONITOR 2000.6000 

The effect of the MONITOR command b to set up parameters within TSX-Plus which will be used to 
monitor the next program run. It does not actually begin the analysis, so there is no rush in running the 
program to be monitored. Once the MONITOR command has been issued, the program to be monitored is 
run by using the standard RUN or R commands. If a program being monitored does a .CHAIN to another 
program, the analysis continues and the times reported will be the composite of the programs run. 
Only one user may be doing a performance analysb at a time. This is because the performance analysis 
histogram buffer is a common memory area that may not be in use by more than one user at a time. An 
analysis is in effect for a user between the time the MONITOR command is issued and the TSXPM program 
is run to display the results of the analysis. Running the TSXPM program terminates the performance 
analysis and allows other users to perform analyses. Note that space for the performance analysis data 
buffer must be reserved when TSX-Plus is generated. 

If the program to be monitored is overlayed and the region to be monitored is in the overlay area, the 
analysis technique is more complex. In this situation, the EMTs described below must be used to control 
the performance analysis as overlay segments are run in the segment being monitored. 

11.2 Displaying the results of the analysis 

After the program being monitored has exited and returned control to the keyboard monitor, the TSXPM 
performance reporting program is used to generate a histogram of the time spent in the region being moni- 
tored. The TSXPM program is started by typing R TSXPM; it responds by printing an asterisk ("*"). In 
response to the asterisk, enter the file specification for the device/file where the histogram is to be written. 
An optional switch of the form /M:nnn may be specified following the file specification. This switch is used 
to specify the minimum percentage of the total run-time that a histogram cell must contain in order to be 
included in the display. If this switch is not specified, the default cut-off percentage is 1%. 
After receiving the file specification, TSXPM prompts for a title line. Enter a line of text which will be 
printed as a page title in the histogram file. Press RETURN if you wish no title. 

The next item of information requested by TSXPM is a set of base offset values. The base offset values are 
optional. Base offsets are useful in the situation where you have several modules making up a program being 
monitored and you want the addresses displayed on the performance analysis histogram to be relative to 
the base of each module. You may specify up to 10 offset values. Each offset value is specified as an offset 
module number (in the range to 9) followed by a comma and the base address of the module (see example 
below). If offset values are specified, TSXPM determines in which module each cell of the histogram falls 
and displays the address as a module number and offset within the module. After you enter all desired 
module offsets, enter RETURN without a value. 

After the base offset values are entered, the histogram will be produced and written to the specified device 
and file. After the histogram is generated, TSXPM prints the asterisk prompt again, at which point you 
may enter the name of another device/file and produce the histogram again or you may type CTRL-C to 
return to the keyboard monitor. 

Example use of TSXPM 

.R TSXPM 

*LP:/M:5 

Title: PERFORMANCE ANALYSIS OF EIGENVALUE CALCULATION 

BaB« offsets: 

> 1.1000 

>2.2134 

>3,5212 

> 

(Histogram is produced at this point) 
♦<CTRL-C> 
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The histogram produced by TSXPM consists of one line per histogram cell. Each line contains the following 
information: 

• the base module offset number (if offsets were specified) 

• the address range covered by the histogram cell (relative to the module base if base offsets were used) 

• the percentage of the total execution time spent at the address range covered by the histogram cell 

• a line of stars presenting a graphic representation of the histogram 

11.3 Performance monitor control EMTs 

For most applications the method described above can be used to do a performance analysis. However, 
in special cases (such as analyzing the performance of an overlayed program) it is necessary to have more 
explicit control over the performance analysis feature as a program is running. The following set of EMTs 
may be used to control a performance analysis. 

11.3.1 Initializing a performance analysis 

This EMT is used to set up parameters that will control a performance analysis. It does not actually begin 
the analysis. The form of the EMT is: 



EMT 



375 



with RO pointing to the following argument block: 

.BYTE 0,136 

.WORD base-address 

.WORD top-address 

.WORD cell-size 

.WORD flags 

where baae-addreea is the address of the base of the region to be monitored, top-addreta is the address of 
the top of the region to be monitored, and eell-aize is the number of bytes to group in each histogram cell. 
If zero (0) is specified as the cell size, TSX-Plus calculates the cell size to use by dividing the number of 
bytes in the region being monitored (top-address minus base-address) by the number of cells available in the 
histogram data area (specified when TSX-Plus is generated). The flaga parameter b used to control whether 
or not I/O wait time is to be included in the analysis. If a value of 1 is specified as the flaga parameter, I/O 
wait time is included in the analysis; if a value of zero (0) is specified, I/O wait time is not included in the 
analysis. 



Error 
Code 



Meaning 



Performance analysis being done by some other user. 
Performance analysis feature not included in TSX-Plus generation. 



Example 
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.TITLE 


DENOPA 






.ENABL 


LC 




Dvaonstratt 


Qfo ot TSX~Plnt ENTt to Inltlallio. start, atop, and 


ttralBfttt « 


parfontanca analysla 






.NCALL 


.EXIT, .PUNT, .LOOIUP. .lEADV, .CLOSE, .TTTOOT 




.QLOBL 


PlIOCT 


Diaplay an octal word In 10 


RtKRTT 


- 62 




ENT arror byta 


SPACE 


- 40 




ASCII 'spaea' 


8TA1 


> 62 




ASCII 'aitarlik' 


SIUT: 


NOV 


fflNITPA.lO 


Point to EMI arg block to 




ENT 


376 


Inltlallia tha parformanca analyali 




BCC 


61 


No arror 




NOVB 


t«RlKRYT,10 


.Vhieh arror T 




ASL 


10 


iConTart to word off a at 




.PlINT 


INIElldO) 


.Print tha arror aaaaaga 




.EXIT 




:And dapart thla world of woo. 


6$: 


NOV 


iSTETPA,10 


;Polnt to EMT arg block to 




ENT 


376 


; Start tha parformanca analyala 




BCC 


10$ 


;No arror 




.PUNT 


tSTlREl 


{Start arror 




.EXIT 




;and dapart. 


10$: 








: Duny 


■•etion 


of coda to do BOBo I/O and compatatlon for analysla 


BEGIN: 


.LOOKUP 


•AlEA,»0,iFILNAN 






NOV 


#10.11 




: Disk I/O 






11: 


.UAOW 


fAlEA , #0 , ffBUFFEl . #266 . , #0 






SOB 


11.1$ 






.CLOSE 


#0 




: Ttnlnal I/O 








.PlINT 


#BUFFE£ 




; Coiq>ata bound 








NOV 


#123460.13 




21: 


NOV 


#12346.10 






CLl 


11 






DIV 


#345. £0 






SOB 


13,2$ 




ENDB: 








NCELLS 


» «ENDB-BEGIN>/2> 


Nuabar of calla in hlitograa 




NOV 


#ST0BLK,10 


Point to ENT arg block to 




ENT 


376 


Stop tho parformanca analyala 




BCC 


16$ 


Chack for arror ratum 




.PtINT 


»ST0RR1 


Only ona arror - PA not Inltlalisad 




.EXIT 




and laara. 


16$: 


NOV 


#HALBLE,10 


Pat HALTPA block addraas in 10 




ENT 


376 


Tarainata tha parformanca analyala 




BCC 


20$ 


Chack for orrora 




NOVB 


•#RR1RYT.10 


Gat arror typa 




ASL 


10 


Conrart to word offaat 




.PlINT 


HLTE&ldO) 


Print out propar arror maaaaga 




.EXIT 




And dapart. 


201: 


TST 


HALFLG 


Chack HALTPA ratnm flag 




BPL 


26$ 


No call orarflowT 




.PlINT 


#OV£YEN 


lasua oTorflow warning 


261: 


BIT 


#1. HALFLG 


I/O tima InclQdadT 




BEQ 


30$ 


Skip maaaaga If not 




.PlINT 


#IOVNOT 


Print I/O wait tima includad mag 


: Print 


• hlttograa of tho porfonaneo u 


lalyaia 


30$: 


CLl 


13 


Sat histogram call eonntar 


SE|: 


CNP 


HSTTBL(13),«04. 


Normallia tha tabla for «4. longaat 




BHI 


40$ 


Too many eonntsT 




ADD 


#2,13 


Point to naxt call 




CMP 


13.#<2*NCELL8> 


End of tabla? 




BLE 


36$ 


No, rapaat 




Bl 


60$ 


All calla laaa than 64. connta new 


401: 


CLl 


13 


la-init. hiatogram call countar 


4S$: 


CLC 




DlTlda aach call count by 2 




101 


MSTTBL(13) 
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50$: 
65$: 

60$: 
66$: 

XNITP&: 



8T&TPA : 
8T0BLK: 
HALBLI 



PINBUF: 

HALFLG: 

HSTTBL: 

HSIEND: 

AB.EA: 

BUFFER: 

FILNAN: 
INIEU: 

HLTEI&: 



INPIG: 

NOCEN: 

NOPA: 

TOSNAL: 

ST&EU: 

STOEU: 

OVEnN: 

lOWNOT: 

OIDONE: 

HSTNSG: 

CILF: 



ADD 

CMP 

BLB 

BE 

.PRINT 

NOV 

CLR 

NOV 

CALL 

.TTYOUT 

MOV 

IIEQ 
.TTYOUT 

iiOB 
.PRINT 

CMP 

CKP 

BLE 
.EXIT 
.BYTE 
.VORD 
.VORD 
.WORD 
.VORD 
• BYTE 
.BYTE 
.BYTE 
.VORD 
.VORD 
.VORD 
.BLIV 
.VORD 
.BLIV 

.BLIV 

.BLIV 

.VORD 

.RADBO 

.VDRD 

.VORD 

.VORD 

.VORD 

.NLIST 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.ASCIZ 

.END 



$2,li ;Polnt to naxt call 

IS,i<2*NCELLS> :End of tabltT 

46$ iNo. ropoat 

S0$ :Co chock all colla again 

ffHSTNSG ;Captlon hlatograa 

•BEGIN, 12 ;8ot llrat anal7sod addroaa 

U ;Iiilt. coll countor 

12,10 iCot road7 to print It out 

PRTOCT jDioplay analysed addroaa 

fSPACE :For formatting 

HSTTBL(R3) ,Ri ;Cat addraaa una countor 

05$ ;No atara on count 

tSTAR ;Prlnt a '** for aach count 

11,60$ 

fCRLF :Go to naxt Una 

(R2) + ,(R3)+ ; Point to naxt addraaa and count 

13,«<2*NCELLS> ;End of hlatograxT 

55$ ;No. dlaplay naxt call 

;Elaa dona. 

0,186 ;EMT arg block for parform. analyala 

BEGIN ; Start analyala addraaa 

Ein)B-2 :End analyala addraaa 

2 ; Count 1 addraaa In aach call 
1 :Inclnda 10 wait tiaa. 

1,136 ;Start Parforaanca Analyala ENT block 

2,136 :ENT arg block to atop parf . analyala 

3,136 ;ENT arg block to ralaaaa analyala 

PINBITF :PA paraaatar boffar addraaa 

HSTTBL :HlatograB labia buffar addraaa 

<HSTEND-HSTTBL> ;HlatograB Tabla buffar langth 

3 :PA four word paraaatar buffar 
;PA raturn flaga 
<2*NCELLS>«3 ;Hlatograa tablo 



:ENT arg block araa 
;Data Input buffar 
;Maka aura buffar la ASCIZ 
;laad tkla flla 
;Inltlallsa PA arror tabla 



:HALTPA Error aaaaaga tabla 



10 

266. 



/DI DENOPAMAC/ 

INPIG 

NOGEN 

NOPA 

TOSNAL 

BEX 

/TINITPA-F-Parforaanea analyala balng dona by anothar uaar./ 

/TINITPA-r-Parforaanca analyala faatura not gannad./ 

/THALTPA-F-Thla Job la not doing a porforaanca analyala./ 

/THALTPA-F-Araa prorldad for hiatogram tabla too aaall./ 

/TINITPA-F-Parforaanca analyala not inltlalliad yat./ 

/T8T0PPA-F-Parforaanca Analyala haa not boon Inltlalliad./ 

/THALTPA-V-Soaa hlatograa call(a) orarflovad during analyala./ 

I HALTPA-I-I/0 wait tiaa Indudad in parforaanca analyala. I 

/ STOPPA-S-Parforaanca Analyala atoppad./ 

/Addraaa Fraquancy/ 

<16><12><200> 

START 



11.3.2 Starting a performance analysis 

This EMT b used to begin the actual collection of performance analysis data. The previous EMT must have 
been executed to set up parameters about the performance analysis before this EMT is called. The form of 
the EMT is: 



e;mt 37 B 

with RO pointing to the following argument block: 
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.BYTE 1.136 
The caxry-flag will be set on return from this EMT if performance analysis has not been initialized yet. 

Example 

See the example program DEMOPA in section 11.8.1 on initializing a performance analysis. 

11.3.3 Stopping a performance analysis 

The following EMT can be used to suspend the data collection for a performance analysis. The data collection 
can be restarted by using the start- analysis EMT described above. This EMT could, for example, be used 
to suspend the analysis when an overlay module is loaded that is not to be monitored. The start-analysis 
EMT would then be used to re-enable the data collection when the overlay of interest is re-loaded. The form 
of this EMT is: 

EMT 37E 

with RO pointing to the following argument block: 

.BYTE 2.136 
The carry flag will be set on return from this EMT if performance analysis has not been initialized yet. 

Example 

See the example program DEMOPA in section 11.8.1 on initializing a performance analysis. 

11.3.4 Terminating a performance analysis 

This EMT is used to conclude a performance analysis. It has the effect of returning into a user supplied 
buffer the results of the analysis and releasing the performance analysis feature for other users. The form of 
this EMT is: 

ENT 375 

with RO pointing to the following argument block: 

.BYTE 3.136 

.WORD parameter-buffer 

.VORD histogram-buffer 

.WORD buffer-size 

where paramtter-buffer is the address of a four- word buffer into which will be stored some parameter values 
describing the analysis that was being performed, htetogram- buffer is the address of the buffer that will 
receive the histogram count values, and buffer-size is the size (in bytes) of the histogram buffer area. 
The values returned in the parameter buffer consist of the following four words: 

1. base address of the monitored region 

2. top address of the monitored region 
8. number of bytes per histogram cell 
4. control and status flags 
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The control and status flags are a set of bits that provide the following information: 



Flag 



1 

100000 



Meaning 



I/O wait time was included in the analysis. 

Some histogram cell overflowed during the analysis. 



The data returned in the histogram buff'er consists of a vector of 16-bit binary values, one value for each cell 
in the histogram. The first value corresponds to the histogram cell that starts with the base address of the 
region that was being monitored. 



Error 
Code 



Meaning 



This job b not doing a performance analysis. 

Area provided for histogram count vector is too small. 



Exaxriple 

See the example program DEMOPA in section 11.3,1 on initializing a performance analysis. 
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Chapter 12 

TSX-Plus Restrictions 



12.1 



System service call (EMT) differences between RT-11 and 
TSX-Plus 



jEMTTulntMTf''V^'ffT"' •." ""l*'^ ^^^-^'"^ implement, some RT-11 system service calls 

.ABTIO Action depends on setting of lOABT system parameter. If lOABT is set to 1 then ABTIO 
operates the same a. RT-11 and calls handler abort entry points. If lOABT is set to then ABT O 
does not caU handler entry points, but instead does . .WAIT on all channels. The default mefhod of 

«quet ~'""" " * ^^^'"'" ^*""" ^''""''"'' «•"■''' f- "-« <>«'"1» »" 'his 

■*^°Ta "cHA^N^rf ""'if^'^n™ " ""'",'"' ''"'""'''• If > CDFN EMT is done, aU channels are purged 
If a .CHAIN 18 done. If .CDFN i, not done, channels are not purged across a chain. 

.CHCOPY Not implemented. 

.CNTXSW Not implemented. 

.CSIGEN/.CSISPC Differ from RT-11 with regard to activation by CTRL-C and CTRL-Z. 

.DEVICE REALTIME privilege is required to use this EMT. 

""""^"x'-Plut ''^''"'''" ''"'"^ ''"'*"'"' ^"''^ '^^ ^"'°^"**^°^ °^ programming device handlers for 

.EXIT Error codes passed back from an exiting program (in byte 53) are interpreted by the keyboard 
monitor according to the following values: f «u uy i,ne jteyooard 



Code 


Meaning 


1 


Success 


2 


Warning 


4 


Error 


10 


Severe 




Fatal 


20 


Unconditional 
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FETCH Returns in RO the address specified for the handler load area AH TSX-Plus device handlers 
are resident, hence the .FETCH EMT performs no operation. If the device handler specified was not 
loaded during TSX-Plu8 initialization, then an error code of is returned. 
.FORK May be used in device handlers but not in user jobs. See the TSX-Plu, System Manager's Guide 

for information on programming device handlers for TSX-Plus. 
GTJB The job number returned in word 1 of the result area is two times the TSX-Plus l^e number That 
il, the first line specified in the system generation will be number 2, the second 4, etc. Words 8 through 
12 of the result area are not altered by this EMT. 
GTLIN Differs from RT-11 with regard to activation by CTRL-C and CTRL-Z. If the program controlled 
terminal option N is used to suspend command file input and a .GTLIN request is issued, then command 
file input cannot be restored. Do not use this method to force keyboard input from withm command 
procedures. Use the optional type argument to the .GTLIN request to force terminal mput rather than 
disabling command file input. 
GVAL Not all of the fixed offsets documented by RT-11 are supported by TSX-Plus Additional negative 
offsets are available to obtain TSX-Plus system values. See Chapter 4 for more information on .GVAL. 

HRESET Action depends on setting of lOABT system generation parameter. If lOABT is set to 1 then 
HRESET calls handler abort entry points. If 10 ABT is set to then .HRESET does not call handler 
entry points but instead does a .WAIT on all channeb. Messages queued on named message channels 
are not canceled. Otherwise, this EMT operates the same as under RT-11. 

.INTEN May be used in device handlers but not in user jobs. See the TSX-Plus System Manager's Guide 
for information on programming device handlers for TSX-Plus. 

.LOCK The TSX-Plus file management module (USR) is always resident and the .LOCK EMT is ignored. 

MAP When issuing a .MAP EMT, the window definition block must specify a non-zero region ID returned 
from the successful creation of a region by use of the .CRRG EMT. A zero region ID will return the 
error code 2. 

.MRKT Expiration of repeated mark-time requests can cause delay of an outstanding .TWAIT request. 

.MTxxx Multi-terminal control EMTs (.MTIN, .MTOUT, .MTPRNT, etc.) are not supported. 

.MTPS The processor priority level may not be changed from user mode, hence this macro performs no 
operation. TSX-Plus provides a special real-time EMT to set the processor priority. 

•MWAIT Not supported. See Chapter 6 on inter-job message communication. 

.PEEK Non-privileged jobs may use .PEEK to access cells within the simulated RMON (addresses 160000 
to 160626) although the .GVAL EMT is a recommended alternative. Jobs with MEMMAP privilege 
may use .PEEK to access the I/O page or low memory cells in kernel space. References to addresses 
in the virtual address range of the simulated RMON (160000 to 160626) are always directed to RMON 
rather than the I/O page. 

.POKE Non-privileged jobs may use .POKE to access cells within the simulated RMON (addresses 160000 
to 160626) although the .PVAL EMT is a recommended alternative. Jobs with MEMMAP privilege 
may use .POKE to access the I/O page or low memory celb in kernel space. References to addresses 
in the virtual address range of the simulated RMON (160000 to 160626) are always directed to RMON 
rather than the I/O page. 

.PROTECT Not supported. See Chapter 8 on real-time programming for information about how to connect 
an interrupt to a TSX-Plus job. 

.QSET TSX-Plus uses an internal pool of I/O queue elements for all jobs hence it is not necessary to define 
additional I/O queue elements in order to perform overlapped I/O. The .QSET EMT is ignored. On 
return, RO contains the address specified for the start of the new elements. 
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.RCVD Not supported. See Chapter 6 which describes inter-job message communication. 

.RELEAS This EMT is ignored. Refer to .FETCH. 

.SCCA All .SCCA requests are treated as local to the job which issues the request. Global SCCA is ignored. 

.SETTOP Returns the job limit in RO but does not actually expand or contract the allocated job region. 
The job region allocation can be changed by use of the MEMORY keyboard command or the TSX-Plus 
specific EMT for this purpose. 

.SDAT Not supported. See Chapter 6 which describes inter-job message communication. 

.SFPA This EMT functions the same as RT-11. It must be used if a job is going to use the floating-point 

unit. 

.SDTTM OPER privilege is required to use this EMT. 

.SPFUN SPFUN privilege is required to use this EMT. SPFUN function code 371 (BYPASS) is unsup- 
ported with the DU handler on extended Unibus hardware and with the MU handler in all configura- 
tions. 

.SRESET Messages queued on named message channels are not canceled. Otherwise, this EMT operates 
the same as under RT-11. 

.SYNCH May be used in device handlers but not in user jobs. When used in a handler, the number of the 
TSX-Plus job that is being synchronized with must be stored in word 2 of the SYNCH block. See the 
TSX-Plua Sytttm Manager's Guide for information on programming device handlers for TSX-Plus. 

.TLOCK This EMT is ignored. 

.TTINR Only honors bit 6 in the Job Status Word (TCBIT$) if a SET TT NO WAIT command has been 
issued, or the running program has send the "U" program controlled terminal option to the system, 
or the program was R[UN| with the /SINGLECHAR switch. 

.TTOUTR Returns with the carry bit set if the terminal output buff"er is full. The following conditions 
must be met: 

1. The .TTOUTR EMT must be used rather than .TTYOUT. 

2. The instruction following the .TTOUTR must not be [BCS .-2|. 
S. Bit 6 must be set in the job status word. 

4. The program must be run in single character activation mode or with the NO WAIT attribute set. 

.TTYOUT If many characters are displayed by .TTYOUT requests from within a completion routine while 
a log file is open, then the job may hang. 

.TWAIT Expiration of repeated mark-time requests can cause delay of an outstanding .TWAIT request. 
.UNLOCK This EMT is ignored. 

.UNPROT Not supported. See Chapter 8 on real-time programming for information about how to connect 
an interrupt to a TSX-Plus job. 

A full list of RT-11 compatible and TSX-Plus specific EMTs is included in Appendix B. The list indicates 
the level of support TSX-Plus provides for each RT-11 compatible EMT. 

12.2 Special program suggestions 

Certain programs use system resources in ways which may not seem obvious or cause behavior which is not 
expected. Some of those features are described in this section to facilitate their use with TSX-Plus. 
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12.2.1 DIBOL 

When DIBOL programs are run under TSX-Plus they must use SUD rather than TSD. Several components 
of the DIBOL system also use I/O channel numbers above 15 (decimal). Reducing the TSGEN parameter 
NUCHN from the default of 20. can result in the error 7INI-ES or ?INI-E4 when using DIBOL or its utilities. 
This can be resolved either by patching SUD or the utility to use lower channel numbers or by regenerating 
TSX-Plus to permit use of higher channel numbers. Set the TSGEN parameter NUCHN to 20., reassemble 
TSGEN, and relink TSX-Plus. 

Keep in mind that record locking does not automatically occur when DIBOL is used with TSX-Plus and 
unless the appropriate TSX-Plus record locking calls are made there is a danger of file corruption. Ap- 
pendix D describes subroutines which may be linked into DIBOL programs to provide access to TSX-Plus 
record locking and inter-program messages. Do not use the DIBOL SEND statement, use an equivalent 
XCALL MSEND instead. 

12.2.2 FILEX utmty 

The FILEX utility is used to read and write "Interchange" format disks. Because of the way FILEX does I/O 
to single density disks in RX02 drives, FILEX must either be run with the MEMLOCK switch or installed 
with the MEMLOCK attribute. 

12.2.3 FORTRAN virtual arrays 

When the object-time system for FORTRAN-IV is generated, three options are available relating to use of 
virtual arrays: NOVIR, VIRP, or VIRNP. If virtual arrays are to be used at all, either VIRP or VIRNP must 
be selected. Under RTllSJ, the VIRNP option is commonly selected. Thb causes FORTRAN virtual array 
handling to directly manipulate the memory management registers in the I/O page. Clearly, in a multi-user 
environment, like TSX-Plus, this is not advisable. The VIRP option is used with RTllXM and must also 
be selected for use with TSX-Plus. TSX-Plus must also be generated with PL AS support; see your system 
manager. If the wrong type of virtual array support is selected, various types of FORTRAN errors may 
occur, including virtual array initialization failures. 

F77 and FORTRAN-IV use PAR 7 to map to virtual arrays. (Page Address Register 7 maps virtual addresses 
160000 to 177777.) TSX-Plus normally maps a job's PAR 7 to a simulated RMON so that older programs 
which require direct access to fixed offsets in RMON may operate without modification. When a program 
requires direct access to the I/O page to manipulate device registers, that is commonly done by mapping 
PAR 7 to the I/O page. This can either be done with the /lOPAGE switch to the R[UN] command or with 
a TSX-Plus EMT. Mapping PAR 7 to the I/O page only conflicts slightly with direct RMON access since 
the parameters available there may also (and should be) obtained with the .GVAL request (SYSLIB ISPY 
function). 

Because use of virtual arrays also affects PAR 7 mapping, mapping PAR 7 to the I/O page causes more 
severe problems when programs must have both virtual arrays and direct I/O page access. The solution to 
thb is to map some other part of the job's virtual address space to the I/O page. TSX-Plus provides an EMT 
to map any part of a job's address space to any physical region, including the I/O page. See Chapter 8 for 
information on mapping to a physical region to resolve the virtual array vs. I/O page conflict. The simplest 
way to do this is to allow PAR 7 to be used for virtual arrays and map PAR 6 to the I/O page. To avoid 
conflict with other parts of the program image, the program must be able to run in less than 48 Kb. Use the 
SETSIZ facility to restrict the program to a total memory space of 48 Kb. Call a MACRO interface routine 
from the FORTRAN program to map PAR 6 to the I/O page. Be sure to normalize I/O page addresses to 
virtual PAR 6 addresses. Note that mapping to the I/O page or to physical memory requires MEMMAP 
privilege. 

12.2.4 IND .ASKx timeoutB 

When using the IND control file processor, the .ASKx directives provide an optional timeout parameter. 
This parameter causes IND to proceed when no terminal response is obtained before the designated timeout 
period. When using .ASKx timeouts under TSX-Plus, it is necessary to SET TT NOWAIT to permit IND 
to proceed when the timeout period expires. 



12.2. SPECIAL PROGRAM SUGGESTIONS 171 

12.2.5 MicroPower /Pascal 

Various program components of MicroPower/Pascal (TM of Digital E^quipment Corporation) should be run 
as virtual programs. That is, they should run without direct RMON access. Under TSX-Plus, this permits 
them to obtain a virtual job address space of a fuU 64 Kb. TSX-Plus must also be generated to allow 64 Kb 
jobs. To define the Pascal compiler and the PASDBG and MIB programs as virtual jobs, use the SETSIZ 
program (see Appendix A) to allow a 64 Kb memoiy partition for them. For example: 

.11 SETSIZ 
*SY:PASDBG/T:64. 



12.2.6 Overlaid programs 

TSX-Plus permits programs to open I/O channels through 2S (octal). However, the overlay handler uses 
channel 17 (octal). Therefore, overlaid programs should not use I/O channel 17 (octal). 
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Appendix A 



SETSIZ Program 



The SETSIZ program can be used to store into a SAV file information about how much memory space should 
be allocated for the program when it is executed. SETSIZ can also be used to set the virtual job flag in the 
job status word (JSW) for a program. 

There are three ways that the amount of memory allocated to a job can be controlled: 

• The TSX-Plus EMT with function code 141 (described in Chapter 4 may be used by a running program 
(to dynamically set the job's size. 

• If a size is specified in a SAV file (by use of the SETSIZ program) the specified amount of memory b 
allocated for the program when it is started. 

• If no size is specified in the SAV file, the size specified by the last MEMORY keyboard command is 
liised. 

Note that the .SETTOP EMT does not alter the amount of memory space allocated to a job but can be 
used by a running program to determine the amount of memory allocated. 

The effect of the SETSIZ program is to store into location 56 of block of the SAV file the number of 
kilowords of memory to aUocate for the program when it is run (the LINK /Kin switch can also be used to 
do this). This value has no effect when the SAV file is run under RT-11 but causes TSX-Plus to allocate 
the specified amount of memory when starting the program. 

If a size value is specified in a SAV file, it takes precedence over the size specified by the last MEMORY 
keybojixd command. The TSX-Plus EMT with function code 141 may still be used to dynamically alter the 
memory allocation while the program is running. 

Most programs allocate memory in two ways: 

• a static region that includes the program code and data areas of fixed size 

• a dynamic region that is allocated above the static region— usually the .SETTOP EMT is used to 
determine how much dynamic space is available to the program. 

The siae of the static region for a program is fixed at link time. If the program is overlaid the static region 
JTa w 1? fP*''*' /'''' ^^^ ^"8®^' °''®'^''y segment as well as the program root. Location 50 in block of the 
bAV file IS set by the linker to contain the address of the highest word in the static region of the program. 

The amount of memory space to be allocated for a SAV file can be specified to the SETSIZ program in either 
of two ways: 

• as the total amount of memory for the program which includes space for the static plus dynamic regions 

• as the amount of memory for the dynamic region only, in which case SETSIZ automaticaUy adds the 
siize of the static region. 
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A.l Running the SETSIZ program 

The SETSIZ program is started by use of the command: 

R SETSIZ 
it responds by displaying an asterisk to prompt for a command line. The form of the command Une is: 

*f ileapec/Bwitch : value 

where fUcept^c is a file specification of the standard form dev:name.ext with the default device being DK and 

the default extension being .SAV. 

If a file specification is entered without a switch, SETSIZ displays information about the size of the SAV file 

and the SAV file is not altered. 

SETSIZ also displays the following status message if the SAV file is flagged as being a virtual image. 

Virtual- image flag is eet 
The virtual message is displayed if either of the following two conditions exist for the SAV file: 

• Bit 10 (mask 2000) is set in the job status word (location 44) of the SAV file. 

• Location of the SAV file contains the RAD50 value for VIR. 

These are the same two conditions that cause TSX-Plus to recognize the SAV file as being a virtual image 
when it is started. 

Examples 

.R SETSIZ 

*TSTPRG 

Base size of program is 22 Kb 

Size of allocation space is 28 Kb 

*SY:PIP 

Base size of program is 10 Eb 

Size of allocation space is 22 Kb 

*PROGi 

Base size of program is 31 Kb 

Ho allocation size specified in SAV file 

Virtual-image flag is set 

A. 2 Setting total allocation for a SAV file 

The /T switch is used to specify the total amount of memory space to be allocated for a program when it is 
run. The form of the /T switch b /T.valut. where value is the number of kilobytes of memory to allocate. 
Note that a decimal point must be specified with the value if it is entered as a decimal value. 
If the /T switch is used without a value, the effect is to clear the TSX-Plus size allocation information in 
the SAV file. 

Examples 

.R SETSIZ 
♦SY:PIP/T:18. 
♦TSTPRG/T:32. 
♦PROGl/T 
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A. 3 Setting amount of dynamic memory space 

The /D switch is used to specify the amount of dynamic memory space to be reserved for a program. The 
SETSIZ program calculates the total amount of space to allocate for the program by adding the static size 
(stored in location 50 of the SAV file by LINK) to the specified dynamic size. The form of the /D switch is 
/D: value, where value is the number of kilobytes of dynamic memory space to reserve. If a program does 
not use any dynamic memory space, the /D switch may be used without an argument value to cause the 
total memory space allocation to be set equal to the static size of the program. FORTRAN programs use 
dynamic space for I/O buffers and the exact amount required depends on the number of I/O channels used. 
However, 4 Kb of dynamic memory space seems to be adequate for most FORTRAN programs. 

Exairiples 

.R SETSIZ 
*SY:PIP/D:11. 
*TSTPRG/D:4. 
*PR0G1/D 



A. 4 Setting virtual-image flag in SAV file 

The /V switch is used to cause SETSIZ to set the virtual-image flag in the SAV file. This flag is bit 10 
(mask 2000) in the job status word (location 44) of the SAV file. 

Setting thb flag indicates that the program will not directly access RMON, although it may do so indirectly 
by use of the .GVAL and .PVAL EMTs. The significance with regard to TSX-Plus is that it allows the 
program to use more than 56 Kb (if that much memory is also allowed by use of a MEMORY command) . 
The virtual-image flag should not be set unless you are sure the job does not need direct access to the RMON 
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Appendix B 



RT-11 & TSX-Plus EMT Codes 



B.l TSX-Plus RT-11 Compatible EMTs 

In the following table, the level of compatibility with the RT~11 functionality of these EMTs is indicated by 
a speciial character in the Code column. The codes are: 

* Not supported, will cause error 
Treated as a nul operation (NOP) 
- Minor differences, see Chapter 12 



EMT Code Chan Name 



S40 


- 


541 




842 




543 


- 


844 




545 




546 





547 





550 




551 




552 


- 


555 





554 


- 


555 




557 


_ 



.TTINR 

.TTYOUT 

.DSTATUS 

.FETCH/.RELEAS 

.CSIGEN 

.CSISPC/.GTLIN 

.LOCK 

.UNLOCK 

.EXIT 

.PRINT 

.SRESET 

.QSET 

.SETTOP 

.RCTRLO 

.HRESET 



Description 

Get character from terminal 

Send character to terminal 

Get device information 

Load/Unload device handlers 

Call command string interpreter 

Get command line 

Lock USR in memory 

Allow USR to swap 

Return to monitor 

Display string at terminal 

Software reset 

Increase I/O queue size 

Set program upper limit 

Reset CTRL-0 

Stop I/O then .SRESET 
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178 
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EMT Code Chan Name 



874 

S74 

874 

874 

874 

874 

874 

874 

874 

874 

874 

874 

875 

875 

875 

875 

875 

875 

875 

375 

875 

875 

875 

375 

375 

375 

375 

375 

375 

375 

375 

375 

375 

875 

375 

875 

375 

375 

375 





1 

2 

3 

4 

5 

6 

07 

10 

* 11 

12 

-13 



1 

2 

3 

4 

5 

6 

7 

10 

11 

12 

* 13 
14 

- 15 
-20 
21 
22 
23 
24 
*25 

* 26 
27 
SO 

31 

31 

82 

* 88 



.WAIT 

.SPND 

.RSUM 

.PURGE 

.SERR 

.HERR 

.CLOSE 

.TLOCK 

.CHAIN 

.MWAIT 

.DATE 

•ABTIO 

.DELETE 

.LOOKUP 

.ENTER 

.TRPSET 

.RENAME 

.SAVESTATUS 

.REOPEN 

.CLOSE 

.READ[C][W] 

.WRIT[Cj[E](W] 

.WAIT 

.CHCOPY 

.DEVICE 

.CDFN 

.GTJB 

.GTIM 

.MRKT 

.CMKT 

.TWAIT 

.SDAT[C|[W] 

.RCVD[C1[W] 

.CSTAT 

.SFPA 

.PROTECT 

.UNPROTECT 

.SPFUN 

.CNTXSW 



Description 

Wait for I/O completion 

Suspend mainline program 

Resume mainline program 

Free a channel 

Inhibit abort on error 

Enable abort on error 

Close channel 

Try to lock USR 

Pass control to another program 

Wait for message 

Get current date 

Abort I/O in progress 

Delete a file 

Open existing file 

Create file 

Intercept traps to 4 and 10 

Rename a file 

Save channel information 

Restore channel information 

Close channel 

Read from channel to memory 

Write from memory to channel 

Wait for I/O completion 

Open channel to file in use 

Load device registers on exit 

Define extra I/O channels 

Get job information 

Get time of day 

Schedule completion routine 

Cancel mark time 

Timed wait 

Send data to another job 

Receive data from another job 

Return channel information 

Trap floating point errors 

Control interrupt vector 

Release interrupt vector 

Special device functions 

Context switch 
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EMT 


Code 


Chan 


Name 


875 


34 





.GVAL 


575 


-34 


1 


.PEEK 


875 


34 


2 


.PVAL 


875 


-34 


8 


.POKE 


875 


35 




.SCCA 


875 


36 





.CRRG 


875 


36 


1 


.ELRG 


875 


36 


2 


.CRAW 


875 


36 


8 


.ELAW 


875 


36 


4 


.MAP 


375 


36 


5 


.UNMAP 


875 


36 


6 


.GMCX 


375 


* 37 





.MTSET 


375 


* 37 


1 


.MTGET 


375 


* 37 


2 


.MTIN 


375 


* 37 


8 


.MTOUT 


375 


* 37 


4 


.MTRCTO 


375 


* 37 


5 


.MTATCH 


375 


* 37 


6 


.MTDTCH 


375 


* 37 


7 


.MTPRNT 


375 


* 37 


10 


.MTSTAT 


875 


40 




•SDTTM 


375 


41 




.SPCPS 


375 


42 




.SFDAT 


375 


43 




.FPROT 



Description 

Get monitor offset value 

Get low memory value 

Change monitor offset value 

Change low memory value 

Inhibit CTRL-C abort 

Create an extended memory region 

Eliminate an extended memory region 

Create a virtual address window 

Eliminate a virtual address window 

Map virtual window to XM region 

Get window mapping status 

Obtain window status 

Set terminal status 

Get terminal status 

Get character from terminal 

Send character to terminal 

Reset CTRL-0 

Lock terminal to job 

Release terminal from job 

Display string at terminal 

Get system status 

Set date and time 

Change mainline control flow 

Change file date 

Change file protection 
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TSX-Plus Specific EMTs 



EMT Code Chan Name 



575 


101 




UNLALL 


575 


102 




LOCKW 


575 


103 




TLOCK 


575 


104 





SNDMSG 


575 


105 





GETMSG 


575 


106 





WATMSG 


575 


106 


1 


MSGCPL 


575 


107 





SPLFRE 


575 


110 





TSXLN 


575 


110 


1 


SUBPLN 


575 


111 


0/1 


ACTODT 


575 


115 




UNLOCK 


575 


114 





TTOBLK 


575 


115 





TTIBLK 


575 


116 





CKTTIE 


575 


116 


1 


GTINCH 


575 


117 





SETTTO 


575 


120 


0/1 


HIEFF 


575 


121 




CKWSHR 


575 


122 




SAVSHR 


575 


125 





CKACT 


575 


125 




SHRFIL 


575 


127 


0-5 


SEND 


575 


152 





STRTDJ 


575 


132 


1 


STATDJ 


575 


152 


2 


ABRTDJ 


575 


185 





DCLBRK 


575 


155 


1 


TTICPL 


575 


154 





MOUNT 


575 


135 





DISMNT 


575 


155 


2 


DMTFLS 


575 


135 


3 


DMTLD 


575 


135 


4 


LDSTAT 


575 


135 


5 


DMTALD 


575 


136 





INITPA 


575 


136 


1 


STRTPA 


575 


136 


2 


STOPPA 


575 


136 


3 


HALTPA 



Description 

Unlock all blocks 

Wait for locked block 

Try to lock a block 

Send message on named channel 

Get message from named channel 

Wait for message on named channel 

Queue message receipt completion routine 

Get number of free spool blocks 

Get line number 

Get subprocess line number 

Reset/set ODT activation mode 

Unlock a block 

Send block of text to terminal 

Get block of text from terminal 

Check for terminal input errors 

Get number of pending input characters 

Set terminal read time-out 

Reset/set high-efficiency mode 

Check for writes to shared file 

Save shared file information 

Check for activation characters 

Declare file for shared access 

Send message to another line 

Start a detached job 

Check detached job status 

Abort a job 

Establish break sentinel control 

Set terminal input completion routine 

Mount a directory structure 

Dismount a directory structure 

Dbmount all mounted file structures 

Dbmount a logical disk 

Get the status of a logical disk 

Dismount all logical disks 

Initiate performance analysis 

Start monitoring performance 

Stop monitoring performance 

Terminate performance analysis 
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EMT 


Code 


Chan 


Name 


575 


137 





TTYPE 


875 


140 





PHYADD 


S75 


140 


1 


PEEKIO 


375 


140 


2 


POKEIO 


375 


140 


8 


BISIO 


375 


140 


4 


BICIO 


375 


140 


5 


MAPIOP 


375 


140 


6 


MAPMON 


375 


140 


7 


LOKLOW 


375 


140 


10 


UNLOKJ 


375 


140 


11 


ATTVEC 


375 


140 


12 


RELVEC 


375 


140 


13 


LOKJOB 


375 


140 


14 


STEALS 


375 


140 


15 


RTURNS 


875 


140 


16 


SETPRI 


375 


140 


17 


MAPPHY 


375 


140 


20 


ATTSVC 


375 


140 


21 


SCHCMP 


375 


141 





MEMTOP 


375 


143 





USERTS 


875 


143 


1 


MAPRTS 


875 


143 


2 


REGRTS 


875 


143 


8 


CLRRTS 


375 


144 





JSTAT 


375 


145 




FILINF 


375 


146 




SFTIM 


375 


147 





GTUNAM 


875 


147 


1 


STUNAM 


875 


147 


2 


GTPNAM 


375 


147 


8 


STPNAM 


375 


150 





SJBPRI 


875 


150 


1 


GSJPRV 


375 


151 




SPHOLD 


375 


152 





SELOPT 


875 


153 





NONINT 


875 


154 





STTSPD 


375 


154 


1 


STTXON 


875 


154 


2 


RTTDTR 


375 


154 


8 


LTTDTR 



Description 

Get terminal type 

Convert virtual to physical address 

Peek into the I/O page 

Poke into the I/O page 

Bit-set into the I/O page 

Bit-clear into the I/O page 

Map PAR7 to the I/O page 

Map PAR7 to simulated RMON 

Lock job into lowest memory 

Unlock job from memory 

Attach to interrupt vector 

Release interrupt vector 

Lock job without re-positioning 

Get exclusive system access 

Relinquish exclusive system access 

Set user mode priority level 

Map to physical memory 

Attach interrupt service routine 

Schedule completion routine 

Control size of job 

Associate with run-time system 

Map run-time system into job 

Define a region for fast map 

Clear region definitions for fast map 

Get job status information 

Get file directory information 

Set file creation time 

Get user name 

Set user name 

Get program name 

Set program name 

Set job execution priority 

Get or set job privileges 

Set spooler HOLD/NOHOLD 

Select terminal option 

Set [nonjinteractive job status 

Set line baud rate 

Reset line XOFF status 

Raise line DTR 

Lower line DTR 
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EMT 


Code 


Chan 


Name 


875 


155 





GETCL 


375 


156 





ALCDEV 


575 


156 


1 


DEALOC 


575 


156 


2 


TSTALC 


575 


157 





MONJOB 


575 


157 


1 


NOMONJ 


575 


157 


2 


STAMON 


575 


160 





GETCXT 


575 


161 





MAKWIN 


575 


161 


1 


SELWIN 


575 


161 


2 


DELWIN 


575 


161 


5 


SPNWIN 


575 


161 


4 


RSMWIN 


575 


161 


5 


PRTWIN 


575 


162 





GISUBP 


575 


162 


1 


INISBP 


575 


162 


2 


GOSUBP 


575 


163 




MNTLD 



Description 

Assign CL unit to a line 
Allocate a device for exclusive use 
Deallocate a device from exclusive use 
Test device exclusive use allocation 
Start monitoring job status 
Stop monitoring job status 
Broadcast status to monitoring jobs 
Acquire another job's file context 
Create a refreshable process window 
Select current process window 
Delete a process window 
Suspend window processing 
Resume window processing 
Print window contents (via WINPRT) 
Initiate or switch to a subprocess 
Initiate a subprocess 
Switch to a subprocess 
Mount a logical disk 



Apjpendix C 

Subroutines Used in Example 
Programs 

C.l PRTOCT— Print an octal value 

The following subroutine accepts a value in RO and prints the six-digit octal representation of that value at 
the terminal. 



.TITLE PRTOCT 
.ENABLE LC 
Print octal ralua of th* 
.MCALL .PUNT 



word In 10 



.GLOBL 
PiTOCT: MOV 
NOV 
NOV 
NOV 
NOV 
1$: NOV 
BIC 
ADD 
NOVB 
CLC 
£0£ 
ASH 
SOB 
.PRINT 
NOV 
NOV 
NOV 
RETURN 
CHARS: .BLKB 
EOW: .ASCII 
.EVEN 
.EIO) 



PRTOCT 

11. -(SP) 

R2,-(SP) 

13. -(SP) 

«E0V,I2 

*0,RS 

RO.Rl 

#177770. Rl 

*'0,R1 

tl.-(&2} 

10 

«-2,R0 

KS.K 

iCHARS 

(SP)4,RS 

(SP}4,R2 

(SP)+,11 

6 
<200> 



;SaT« 11-13 on tht stack 



iPolnt to ond of 6 char output buffer 

;Sot up countor for (i ehara 

:Stt up aaak for low 3 blti (la digit) 

;6tt low 3 bita 

jConTart to ASCII 

;F111 octal digits In froa and 



iShift out blta Juat conTtrtod 
;l«p«at for 6 chart 
:0l8pla7 raanlt at eonaolo 
;loBtor* roglatara 11-13 



:6 char output buff or 

:No CI taralnator for .PlIHT 



C.2 PRTDEC— Print a decimal value 

^.tff r^'r.' '"Y""/"' "^""'^ " '"''" '" ^^ ""^ P""'' "" ■^'"""^ representation of that value at the 

terminal with no leading zeroes. 
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.TITLE PiTDEC 
.ENABL LC 
Print th« dtclmal ralu* ol 



.NCALL 
.GLOBL 
PITDEC: NOV 
NOV 
NOV 
NOV 
II: CLl 
DIV 
ADD 
NOVB 
NOV 
BNE 
.PlINT 
NOV 
NOV 
lETU&N 
.BLIB 
BOFEND: .BYTE 
.EVEN 
.END 



.PEINT 

PETDEC 

E1,-(SP) 

E2,-(SP) 

»BUFEND,E2 

EO.El 

EO 

#10., EC 

•'O.El 

E1.-(E2) 

EO.El 

It 

E2 

(SP)4,E2 

(SP)+.E1 

B 

200 



tha word In EO 



;SftT« El «nd E2 

■.Point to and ol output buff or 

;8tt up for DIV 

:Cl«&r high word for DIV 

;0«t loaat aignificant digit 

:Nt)ca rasaindar Into ASCII 

;8aTa digit In output bnflar 

;8at up for naxt DIV 

: Until nothing laft 

;DiBpla7 nuabar at tha taralnal 

-.Eattora El and E2 



;B char output buffar 

;No CE tarmlnator for .PEINT 



C.3 PRTDE2— -Print a two-digit decimal value 

The following subroutine accepts a value in RO and prints the decimal representation of it at the terminal. 
The value must be in the range of to 99. 



.TITLE PETDE2 
.ENABLE LC 



Print 



PETDE2: 



2$: 



BUFFEE: 



a 3-digit deciaal ralna 


from EO 


.NCALL 


.PEINT 




.aLOBL 


PETDE2 




NOV 


El.-(SP) 




NOV 


E2.-(SP) 




NOV 


E3.-(SP) 




NOV 


EO.El 


;6at cop7 of char in El 


NOV 


«<BUFFEE«2>,E2 


: Point to buffar 


NOVB 


#200 . (E2) 


:8at and for .PEINT 


NOV 


#2.ES 




CLE 


EO 


;Claar high word for DIV 


DIV 


#10.. EO 


;Gat low digit 


ADD 


#'0.E1 


;ConTart low digit to ASCII 


NOVB 


E1.-(E2) 


;Put digit in char buffar 


NOV 


EO.El 


:Eoll quotiant for naxt DIV 


SOB 


E3.2I 


:Twe digit • only 


.PEINT 


«BUFFE£ 


;Diapla7 tha raault 


NOV 


(SP)+,ES 




NOV 


(SP)«.E2 




NOV 


(SP)*.E1 




EETUEN 






.BLIB 


6 




.EVEN 






.END 







C.4 PRTR50 — Print a RAD50 word at the terminal 



The following subroutine accepts a one word RAD50 value in RO and prints its ASCII representation at the 
terminal. 



C.5. R50ASC— CONVERT A RAD50 STRING INTO AN ASCIZ STRING 
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.TITLE 

.ENABL 
; Display tht 

.NCALL 

.GLOBL 
PiTlBO: NOV 

NOV 

NOV 

NOV 

CLE 

DIV 

NOV 

NOV 

CLE 

DIV 

.TTYOOT 

.TTYODT 

.TTYOUT 

NOV 

NOV 

NOV 

EETUEN 

.NLIST 
160TBL: .ASCII 

.EVEN 

.END 



PETEEO 
LC 
&ADEO Talue 
.TTYODT 
PETEEO 
11. -(SP) 
14. -(SP) 
1E,-(SP) 
10, EE 
14 

fE0.E4 
IE. 11 
14, IE 
14 

«EO,U 
1E0TBL(14) 
lEOTBL(EE) 
EEOTBL(El) 
(SP)4.EE 
(SP)*.E4 
(SP)+,11 

BEX 

/ ABCDEFGHIJILNNOPQESTUWXYZI. 012S4E6780/ 



of a word paatad in 10 



;Naad placa to atora laat char 
:Naad 14 and IE for DIV 

;Gat copy of rO into dividend 
;Zaro high word for DIV 
{Extract laat char 
;8aTa last char (raaiilndar) 
:NoTa quotient for next DIV 
:Zero high word for tacond DIV 
;Cat flrat and aacond chara 
{Display first char (quotient) 
: and aacond char (niaainder) 
; and laat char 
:lestore registers 



C.5 R50ASC — Convert a RAD50 string into an ASCIZ string 

The following subroutine accepts a pointer in RO to an argument block containing pointers to a RAD50 
input atring and an output buffer to hold the ASCII equivalent of the RAD50 string, and a word containing 
the number of characters to be converted. 



.TITLE EEOASC 
Convert EADEO value into 
Output buffer must be at 

.GLOBL lEOASC 



ASCII 

least S characters extra long 



IfiOASC 



It: 



2(: 



.DSABL 

NOV 

NOV 

NOV 

NOV 

NOV 

NOV 

NOV 

NOV 

TST 

BLE 

ADD 

NOV 

CLl 

DIV 

NOVB 

NOV 

CLl 

DIV 

NOVB 

NOVB 

SUB 

BGT 

ADD 

CLEB 



GBL 

11. -(SP) 

12, -(SP) 

IS.-(SP) 

14, -(SP) 

lE.-(SP) 

(10)4. El 

(10)-».E2 

(10) ,ES 

E3 

2$ 

«S.E2 

(E1)^,EE 

E4 

ffE0.E4 

lEOTBL(EE), 

E4,EE 

E4 

ifiO,E4 

lEOTBL(EE), 

EE0TBL(14).- 

*S,1S 

1$ 

1S,E2 

(E2) 



{Pointer to input buffer 
{Pointer to output buffer 
{Number of chars to convert 
{Dividend low word and quotient 
{Dividend hi word andl resaindar 
{Fetch input buffer Address 
: Output buffer address 
{Number of chars to convert 
{Any chars to convertT 
{Branch if not 
{Point to end of 3 char aot 
{Fetch lADEO value 
{Set up for divide 
{Get first char 
■1(12) {Put S/S into output buffer 
{Set up for divide 

{Convert next char 
2(12) {Put 2/3 into output buffer 
3(12) {Put 1/3 Into output buffer 

{Converted 3 chars this round 

{Branch if more chars left to convert 

{Locate last real char 

{Nake output string ASCIZ 
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MOV 



(EP)*.»B 



NOV 


(SP)* 


.u 


NOV 


(SP)* 


,&s 


NOV 


(SP)* 


.ia 


NOV 


(SP)* 


.11 


lETUlN 






.HLIST 


BEX 




: .ASCII 


/ ABC 


DEF 


.EVEN 






.END 







0123466789/ 



C.6 DSPDAT— Print a date value at the terminal 

The following subroutine accepts a date value in RO and prints the date representation at the terminal. 



Print a 



NONNSI 
DATNSK 
T&N8K 
DSPDAT: 



.TITLE DSPDAT 
.KNABL LC 

data Talua froa 10 
.NCALL .PRINT 
.GLOBL DSPDAT, PETDEC 
- 036000 
• 001740 
> 000037 



NOV 
NOV 
BIG 
ASH 
CALL 
NOV 
BIG 
ASH 
ADD 
.P&INT 
NOV 
BIG 
ADD 
CALL 
NOV 
EETDIN 
.HLIST 
NONTBL: .ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.ASCII 
.EVEN 
.END 



11. -(SP) 

10,11 

f-CDAYNSK.lO 

i-6,10 

PITDEC 

11,10 

f-CNOHNSX.lO 

#-7,10 

f NONTBL. 10 

10 

11,10 

t'CYlMSX.lO 

f72..10 

PITDEC 

(SP)*,ll 



;6at copy of data In 11 

:Nagk in only day bita (6-9) 

:Shlft down 

;Prlnt It out 

:Gat fraah copy of data 

;Uaa only month blta (10-13) 

;Shlft dovn to Indax into Bonth tablo 

;Polnt Into tabla 

;Dlaplay tha aonth 

;Fra8h copy again 

;DBa only yaar blta 

;Taar alnca 1972 

:Dlaplay tha yaar 



BEX 

/-NON-/<200><0><0> 

/-Jan-/<200><0><0> 

/-Fab-/<200><0><0> 

/-Mar-/<200><0><0> 

/-Apr-/<200>C0><0> 

/-May-/<200><0><0> 

/-Jun-/<200><0><0> 

/-Jul-/<200><0><0> 

/-Aug-/<200><0><0> 

/-8ap-/<200><0><0> 

/-Oct-/<a00><0><0> 

/-NoT-/<200><0><0> 

/-Dae-/<200><0><0> 



C.7 DSPTI3 — Display a 3-second format time value 

The following subroutine accepts a special three-second time value in RO and prints the time value at the 
terminal. 



C.8. ACRTI3-C0NVERT A TIME VALUE TO SPECIAL S-SECOND FORMAT 
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.TITLE 


DSPTIS 


.ENABL 


LC 


: Dltplay Bpaclal S-itc form* 


.NCALL 


•TTYOUT 


.GLOBL 


DSPTIS, PITDE2 


DSPTI3: NOV 


11. -(8P) 


NOV 


10,11 


CLK 


&0 


DIV 


#20., 10 


NOV 


11. -(SP) 


ASL 


11 


ADD 


11. (SP) 


NOV 


10,11 


CLE 


10 


DIV 


#60.. 10 


MOV 


11. "(SP) 


CALL 


P1TDE2 


•TTYOUT 


#•: 


NOV 


(SP)+,10 


CALL 


P1TDE2 


.TTYOUT 


#•: 


NOV 


CSP)*,10 


CALL 


P1TDE2 


NOV 


(SP)+,11 


RETOEN 




.END 





tlaa Talut from 10 



:S«t op for dlTld* 

;GBt f ol S-SEC'S tlnct midnight 

:Put on stack 

;2X S-SEC'S 

;Plui IX glTVB SX - iiacondB 

:Get r*Bt of tlBo 

;S«t up for next dlrldc 

;Got nuHbor of alnuttt 

;And BaTo on atack 

; What 'a laft la hours, dlaplaj 

;locoTBr alnutas 
;Displa7 alnutoa 

;lBC0TBr Bteonda 



C.8 ACRTI3— Convert a time value to special 3-second format 

The following subroutine accepts a time value from the terminal and converts it to a special three-second 
mternal format. The value is returned in RO. special cnree-second 



•TITLE 
•ENABL 
: Accept a tlaa 
: a apacial S-s 

•GLOBL 
AC1TI3: NOV 
NOV 
NOV 
CLE 
CLl 
CLl 
CALL 

:bcs 

MUL 

NOV 

TST 

BNE 

CALL 

»CS 

mi 

MOV 
TST 
BNE 
CALL 
B'CS 
CLl 
DIV 
It : ADD 

ADD 
NOV 



ACITIS 
LC 

froM tha keyboard and rotnm It in 
•eond format in 10 
ACITIS 



11. -(SP) 

12. -(SP) 

IS.-(SP) 

HOUIS 

MINIT8 

12 

GETNim 

at 

i<60.«20.>,lS 

1S,H0D1S 

KDNEll 

It 

GETNUN 

2t 

f20.,lS 

1S.NINIT8 

KDNEll 

It 

GETNUN 

at 

12 
fS,12 

NINITS,12 
HOUIS. 12 
12,10 



;Nakt surt it's raantrant 



:Accrua daelaal hours 

; latum with orror 

;ConTart hours to 3-sac parlods 

;SaTa hours in S-sse units 

;Did va hit and of inputT 

;Tas, ratum ralua 

;Accrua daciaal Blnutaii 

; latum with arror 

sConTort alnutas to 3-iiac pariods 

;SaTa alnutas in 3-sac units 

;End of input T 

:Taa. raturn Talua 

iAccrua daciaal saconds 

: latum with arror 

sConrart saconds into S-sac pariods 

; Quotient stajs in 12 

;Add in S-socs froa ainutas 

;Add in 3-sacs froa hours 

: latum it in 10 
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CLC 




Bl 


SI 


2%: SBC 




SI: MOV 


(SP)-,1S 


NOV 


(SP)*.B2 


NOV 


(SP)+.E1 


lETU&N 




GETHUH: CLl 


mmRu 


CLE 


IS 


11 : NOVB 


(10) ♦.11 


CMPB 


ll.f'O 


BLT 


21 


CHPB 


ll.i'B 


BGT 


21 


NUL 


•10.. 13 


SITB 


fO.ll 


ADD 


11, IS 


BE 


11 


at: CNPB 


ll.i': 


BEq 


SI 


IMC 


NUNEll 


TSTB 


11 


BEQ 


SI 


SEC 




lETUIN 




S$ : CLC 




lETinLN 




MOUIS: .WOIO 





NIHIT8: .WORD 





tniNEU: .VO&D 





.END 





;8a7 no error 

;ltturn 

;Say thore »»• •» orror 



;8»y no orror ytt 

;Initialixo numbor 

:Qot noxt digit into 11 

;L«si than 'OT 

;Mot a digit 

:Groat«r than '9T 

;Not a digit 

;Shlft prtTioui digit* 

.ConTtrt eurront digit to binary 

:And Ineludo in nmibor 

:Ott digit* til noxt aoparator 

;!• it a Itgal aoparatort 

jTaa. rtturn 

;Say it may ba and 

;Vaa it a nul (and of input atringjT 

;T*i. ratum 

;No. aay invalid input 

:Error ratum 

;No error 



C.9 ACRDEC— Convert an ASCII decimal value to a numeric 
value 

The foUowing .ubroutin. converts the «cii decun.l vU«. in Rl to a numeric value and place, it in RO. 



.TITLE ACIDEC 

Accrue an ASCII decimal number fro. an input atring Into a word in 10 
Aceepta Taluea OTor range to S2767. 



Input a : 
11 

Output a : 
10 
11 



Pointi to buffer containing ASCII atring containing number 



Contalna internal repreaantation of number 
Pointa paat and of input atring 



.NCALL .PlIHT 
.6L0BL ACIDEC 

ACIDEC: NOV 12. -(SP) 



II: 



NOV 

CU 

CLl 

NOVB 

BEq 

BIC 

CMPB 

BNE 

IHC 



1S,-(SP) 
IS 

MEGFLG 

(11) ♦.10 

DONE 

#-C177.10 

lO.f- 

21 

NEGFL6 



;SaTe legiatera 

'.Clear number 

:Init. HEGatlTO FLaG 

:Fetch next digit 

: Branch if no more to couTort 

iNaak out anything non-aacii 

:N*gatiTe numberT 

iBl if not 

ilemember negatlTO 
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B& 


it 




a$: 


CMPB 


iO,«'. 






BEq 


DONE 






CNPB 


to, #40 






BEQ 


DONE 






CNPB 


10, #64 






BEQ 


DONE 






SUB 


#'0.I0 






BNI 


IKVNUN 






CNF 


10, #0. 






BGT 


INVNITN 






NUL 


•10., U 






BCS 


INVNUN 






ADD 


10,13 






BCS 


INVNUN 






BE 


11 




DONE: 


NOV 


13.10 






TST 


NEGFLG 






BEQ 


1< 






NEG 


10 




!•: 


CLC 








BI 


ALLDON 




IinrNUN: 


.PilNT 
SEC 


*BADNUN 




ALLDON: 


NOV 


(SP)*.13 






NOV 


(SP}«,12 






lETUEN 








.NLIST 


BEX 




NBGFLG: 


.VO&D 







BiONUN: 


.ASCIZ 


/Illtgal nmibar 


/<r> 




.LIST 


BEX 






.EVEN 








.EKD 







;G«t ntxt ehiir 

:D«clBal point? 

;Bruich If so, Intsgtrt only 

;8pactT 

:Branch if inparktor 

;CoBuT 

;Bruich If separator 

iConTtrt aacil to nuabor 

;Branch If lisTalid nuabor 

:6r«attr than OT 

;B1 if inralld niuabor 

:Crcla prtTloat digita 

:Braneh on oTorflow 

;Add in now digit 

; Branch on ororflow 

:l«paat until all digits included 

;l«tam roanlt in 10 

iNogataT 

:B1 if not 

:Nagatal 

: Signal 01 rotnm 

;Skip arror staff 

:Bad aiubor massaga 

;lastoro raglstars 



CIO RADASC — Convert a RADIX-50 string to ASCII 

The folllowing subroutine converts a RADIX-50 string whose address is in R5 to ASCII. R4 contains the 
number of words to convert and R3 points to the end of the converted string. 



.TITLE lADASC 
.ENABL LC 



.GLOBL lADASC 

ConTort a 1A060 string whosa addrtss is in rB to audi. 14 contains 
ths nuBber of words to conrart and rS containa tha storaga raault 



lADASC: 



II: 



NOV 


11. -(SP) 




MOV 


12. -(SP) 




NOV 


(16) -^.11 




CLl 


10 




DIV 


#60*60,10 




HOVB 


lADTAB(lO) 


(13) + 


CLl 


10 




DIV 


#60,10 




NOVB 


lADTAB(lO) 


(13) + 


HOVB 


lADTAB(ll) 


(13) ♦ 


SOB 


14,1$ 




MOV 


{SP)+.12 




MOV 


(SP)*,11 





SaTa rl 

Sara rS 

Obtain a word to conTort 

Claar high ordar 

laolata tha high lattar 

Stora conTortad character 

Claar high ordar 

laolata tha alddla lattar 

Stora conTortad character 

Store last eonTsrted character 

Loop until all words conrortad 

lestore r2 

lestore rl 



190 
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EETDIM 



.HLIST BEX 
UDTAB: .ASCII / ABCDEFaHIJILKNOPqiSIUV¥XYZ$ . 012S4B6789/ 
.LIST BEX 

.EVEN 
.END 



Appendix D 

DIBOL TSX-Plus Support 
Subroutines 



A set of subroutines is provided with TSX-Plus to perform DIBOL record locking and message transmission 
functions. DIBOL ISAM files are not supported by TSX-Plus. These subroutines may not be used with 
DBL, which provides most of their functionality separately. Note that If these TSX-Plus features are to be 
used, they must be enabled when the TSX-Plus system is generated. 

D.l Record locking subroutines 

The record locking subroutines coordinate access to a common file being shared and updated by several 
TSX-Plus users. The five subroutines parallel the operation of the DIBOL statements: OPEN, CLOSE, 
READ, WRITE and UNLOCK. The normal DIBOL I/O statements cannot be used to perform record 
locking under TSX-Plus. 



D.1.1 Opening the file 

The first subroutine is used to open a shared file in update mode. The form of the call is: 
XCALL FOPENCchan.devlbl.errflg) 

where chan is a decimal expression that evaluates to a number in the range 1-15. This is the channel number 
used in associated calls to FREAD, FWRIT, FUNLK and FCLOS subroutines. Devlbl is the name of an 
alphanumeric literal, field or record that contains the file specification in the general form dey:f ilnam.ext. 
The file size must not be specified with the file name. An optional /W switch may be appended to the file 
name to cause the "WAITING FOR devifUe" message to be printed. Errflg is a numeric variable capable of 
holding at least two digits, into which is stored an indication of the result of the FOPEN call. The following 
values aje returned: 



Error 
Code 




17 
18 
72 

7S 



Meaning 



No error. File is open and ready for access. 

File name specification is invalid. 

File does not exist or channel is already open. 

Too many channels are open to shared files. Re-gen TSX-Plus and 

increase the value of MAXSFC parameter. 

Too many shared files are open. Re-gen TSX-Plus and increase 

the value of MAXSF parameter. 
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The FOPEN subroutine should only be used to open files that will be updated by several users. The normal 
DIBOL OPEN READ/WRITE sequence should be used for other files. Several files may be opened for 
update by calling FOPEN with different channel numbers. The ONERROR DIBOL statement does not 
apply to these record locking subroutines. Instead the errflg argument is used to indicate the outcome of 
the operation. 



D.1.2 Locking and reading a record 

The FREAD subroutine is used to lock and read a record. The form of the call is: 

XCALL FREAD(chaii,r©cord.r«c-#.'T* or 'W. errflg) 

where chan is a decimal expression in the range 1-15 that identifies a channel previously opened by FOPEN. 
Record is the name of the record or alphanumeric field in which the record read is to be placed. Ree-# is a 
decimal expression that specifies the sequence number of the record to be read. This value must be between 
1 and the total number of records in the file. It may be larger than 65585. 

*T' If 'T' is specified as the fourth parameter, FREAD will return a value of 40 in errflg if the requested 
record is locked by some other user. 

' W If • W is specified, FREAD will wait until the record b unlocked by all other users and will never return 
the record- locked error code. 

Errflg is a decimal variable into which is stored one of the following values: 



Error 
Code 





1 

22 

28 

40 

71 
72 



Meariing 



"No error. Record has been locked and read. 

End-of-file record has been read. 

I/O error occurred on read. 

Invalid record number (possibly beyond end of file). 

Record locked by another user. (Only returned if *T' is specified 

as fourth argument.) 

Channel was not opened by calling FOPEN, or channel not open. 

Request to lock too many blocks in file. Re-gen TSX-Plus and 

increase value of MXLBLK parameter. _^^____ 



The FREAD subroutine functions like the DIBOL READ statement. However, whereas the DIBOL READ 
statement always returns an error code (40) if the requested record is locked, FREAD offers the user a choice: 
If 'T' is specified as the fourth argument to FREAD, a code of 40 will be returned in errflg if the record is 
already locked. If * W is specified a» the fourth argument and the record is locked, FREAD does not return 
an error code, but rather waits until the requested record is unlocked. It is much more efficient to wait for 
a locked record by using the *W* option rather than re-executing the FREAD with the *T' option. It may 
be desirable to perform the first FREAD using the 'T' optionj If the record is locked a "WAITING FOR 
RECORD . . .*' message can be displayed on the user's console and another FREAD can be issued with the 
'W* option to wait for the record. On return from this FREAD the WAITING message can be erased. 

Note that although record locking is requested on a record by record basis, the actual locking is done on a 
block within fiJe basb. A block contains 512 characters. The result of this is that a record is locked if any 
record contained in the same block(s) as the desired record is locked. 

Once a record is locked and read using FREAD, the record remains locked until the program performs one 
of the following operations: 
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• Issues an FWRIT to the channel from which the record was read. 

• Issues another FREAD to the channel. 

• Issues an FUNLK to the channel. 

• Issues an FCLOS to the channel. 

• Terminates execution by use of the STOP statement or because of an error. 

The same set of rules that apply to the DIBOL READ statement apply to FREAD. 

D.l. 3 Writing a record 

The FWRIT subroutine is called to write a record to a shared file. The form of the call is: 

ICALL FtfRlKchan, record, rec-#,errflg) 

where chan is the channel number associated with the file, record is the name of the record or alphanumeric 
field that contains the record to be written, ree-# is a decimal expression that specifies the sequence number 
of the record to be written (it may be larger than 655S5), and errflg is a decimal variable into which is stored 
one of the following values: 



Error 
Code 




22 

28 



Meaning 



No error. 

I/O error occurred during write or channel is not open. 

Bad record number specified. 



The FWRIT subroutine writes the indicated record to the file then unlocks any blocks that were locked by 
the program. FWRIT appends a <CR><LF> to the end of the written record as does the DIBOL WRITE 
statement. The rules for the DIBOL WRITE statement also apply to FWRIT. 

D.l. 4 Unlocking records 

The FUNLK subroutine is used to unlock records that were locked by calling FREAD. The form of the call 
is: 

XCALL FUNLK (chan) 

where ehan is the channel number. 

D.l. 5 Closing a shared file 

The FCLOS subroutine is called to close a channel that was previously opened to a shared file by calling 
FOPEN. The form of the call is: 

XCALL FCLOS (chan) 

where chan is the channel number. 

FCLOS unlocks any locked records and closes the file. Other users accessing the file are unaffected. After 
calling FCLOS^ the channel may be reopened to some other file. 
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D.1.6 Record Locking Example 

In the following example & program performs the following functions: 

1. Opens a shzu-ed file named INV.DAT on channel 2. 

2. Reads a record whose record number is stored in RECN into the field named ITEM and waits if the 
record is locked by another user. 

5. Updates the information in the record. 

4. Rewrites the record to the same position in the file. 

5. Closes the shared file. 

XCALL F0PEN(2.'INY,DAT'.ERRFL) 
XCALL FREAD(2.ITEM,,IIECK.'W,ERRFL) 
;<updat« record> 
XCALL FWRIT(2.ITEM,RECN,ERRFL) 
XCALL FCL0S(2) 

D.1.7 Modifying programs for TSX-Plus 

It is a straightforward process to modify DIBOL programs to use the TSX-Plus record locking subroutines. 
OPEN, CLOSE, READ, WRITE, and UNLOCK statements that apply to shared files must be replaced by 
the appropriate subroutine cjills. Error conditions must be tested by IF statements following the subroutine 
calls rather than by using the ONERROR statement. 

D.2 Message communication subroutines 

Three subroutines are included in the DIBOL support package to allow programs to transfer messages to 
each other. When running under TSX-Plus these subroutines must be used instead of the DIBOL SEND 
and RECV statements. 

D.2.1 Message Channels 

Messages are transferred to and from programs by using TSX-Plus Message Channels. A message channel 
accepts a message from a sending program, stores the message in a queue associated with the channel and 
delivers the message to a receiving program that requests a message from the channel. Message channels 
are totally separate from I/O channels. The total number of message channels is defined when TSX-Plus is 
generated. 

Each active message channel has associated with it a one to six character name that is used by the sending and 
receiving programs to identify theMiannel. The names associated with the channels are defined dynamically 
by the running programs. A messlge channel is said to be active if any messages are being held in the queue 
associated with the channel or if any program is waiting for a message from the channel. When message 
channels become inactive they are returned to a free pool and may be reused by another program. 

The DIBOL SEND command directs a message to a program by using the name of the receiving program. 
Under TSX-Plus, a sending program transmits a message using an arbitrary channel name. Any program 
may receive the message by using the same channel name when it requests a message. 
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D.2.2; Sending a Message 

The MSEND subroutine is called to queue a message on a named channel. If other messages are already 
pending on the channel the new message is added to the end of the list of waiting messages. The form of 
the call is: 

XCALL HSEND (chan , message , errf Ig) 

where chan is an alphanumeric literal or variable that contains the channel name (1 to 6 characters), message 
is an alphanumeric or decimal literal, field or record that contains the message to be sent, errflg is a decimal 
variable into which will be stored one of the following values: 



Error 
Code 



Meaning 



No error. Message has been sent. 

All message channels are busy. (Re-gen TSX-Plus and increase the 

value of MAXMC parameter) . 

Maximum allowed number of messages are being held in message 

queues. (Re-gen TSX-Plus and increase the value of MAXMSG 

parameter) . 



Note that the maximum message length that may be transferred is defined during system generation by 
the MSCHRS parameter. If a message longer than this is sent, only the first part of the message will be 
delivered. 

D.2.3 Checking for Pending Messages 

The MSGCK subroutine may be called to determine if any messages are pending on a named channel. The 
form of the call is: 

XCALL NSGCKCchan.message.errflg) 

where chan is an alphanumeric literal or variable that contains the name of the channel (1 to 6 characters), 
meaaage is an alphanumeric or decimal field or record where the received message is to be placed, errflg is 
a decimal variable into which will be stored one of the following values: 



Error 
Code 



Meaning 



No error. A message has been received. 

No message was queued on the named channel. 



If a received message is shorter than the receiving message field the remainder of the field is filled with 
blanks. If the message is longer than the field, only the first part of the message is received. 

D.2.4 Waiting for a Message 

The MSGWT subroutine is used by a receiving program to suspend its execution until a message is available 
on a named channel. It b much more efficient for a program to wait for a message by calling MSGWT rather 
than repeatedly calling MSGCK. The form of the call is: 



XCALL NSGVT (chan. message, errflg) 
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where the arguments have the same meaning as for MSGCK, and the following values may be returned in 
err fig: 



Error 
Code 



Mear^ing 



No error. A message has been received. 
All message channels are busy. 



D.2.5 Message Examples 

In the following example a program sends a message to another program by using a message channel named 
SORT and then waits for a reply to come back through a message channel named REPLY. 

XCALL MSEND ( ' SORT ' . ' DK : PAYROL . DAT ' . ERRFL) 
IF(ERRFL.NE.O)G0 TO ERROR 
XCALL MSGWT ( ' REPLY ' . M8GBF . ERRFL) 
IF(ERRFL.NE.O)GO TO ERROR 

D.3 Using the subroutines 

The subroutines described above are part of the MACRO program called DTSUB.MAC. Once assembled, 
the object file for DTSUB (DTSUB.OBJ) may be linked with DIBOL programs that use the record locking 
or message facilities. An example of a LINK command is shown below. 

R LINK 

♦PROG=PROG . DTSUB . DIBOL 

D.4 Miscellaneous functions 

D.4.1 Determining the TSX-Plus line number 

The TSLIN subroutine can be called to determine the number of the TSX-Plus time-sharing line from which 
the program is being run. Real lines are numbered consecutively starting at 1 in the same order they are 
specified when TSX-Plus is generated. Detached job lines occur next and subprocesses are numbered last. 
The form of the call of TSLIN is: 

XCALL TSLIK(lnum) 

where Inum is a numeric variable capable of holding at least two digits into which is stored the TSX-Plus 
line number value. 
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.ABTIO, 167 

ACRDEC, example program, 188 
ACRTI3, example program, 187 
Activation characters, 15 

Checking for, 84 

CTRL-D, 156 

Defining, 20 

Field width, 21 

ODT activation mode, 29 

Resetting, 21 

Time-out activation, 82 
Adapting RT-11 Real-time programs, 144 
Address 

Debugger, 156 
Administrative control, 2 
Allocating devices, 66 
ATTVEC, example program, 142 

Baud rate 

Setting, 61 
Block locking 

See Shared files. 
BPT Instruction 

Debugger, 152 
Break sentinel control, 88 
BYPASS, 118, 116 

Cl handler 

see CL handler. 
Caching 

Data, 91 

See TSX-PluB Syetcm Manager's Guide. 

Shared file, 82 
Carriage-return 

Automatic line-feed, 22 
.CDFN, 167 
.CHAIN, 167 

Channel numbers, 169, 171 
Chapter summaries, 8 
Character echoing, 20 
•CHCOPY, 167 
CL handler, 101 

As a spooled device, 104 

control character processing, 104 

Cross connection, 108 

Flow control, 104 



I/O operations, 104 

Installing, 101 

Modem control, 101, 107 

Special functions, 105 

VTCOM/TRANSF support, 102 
CL units, 3 

Assigning, 64 
.CNTXSW, 167 
Command files 

Controlling input, 21 
Common data areas, 145 
Communication 

TSX-Plus to other machines, 108 
Communication line handler 

See CL handler, 104 
Completion routine 

Connecting to an interrupt, 140 

Scheduling, 148 

Scheduling message, 97 
Configuration requirements, 1 
Control characters 

CTRL-C, 20 

CTRL-D, 151, 152, 156 

CTRL-), 19 
Cooperative file access 

See Shared files. 
Creating a window, 72 
.CSIGEN, 167 
.CSISPC, 167 

Data caching, 91 

See TSX-Plut System Manager's Guide. 

Shared file, 82 

Suppression of, 91 
Data watchpoint 

Debugger, 151 
Debugger, 151 

Address 0, 156 

Address relocation, 154 

Breakpoints, 154 

CTRL-D, 156 

Data watchpoints, 154, 155 

Features, 151 

Format register, 155 

Internal registers, 155 
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Mask register, 155 
Overlays, 156 
RAD50 values, 154 
Relocation base, 154 
Shared run-time, 156 
Single stepping, 15S, 154, 156 
Special activation characters, 156 
Special terminal mode, 156 
Speed, 156 

Symbolic decoding, 153, 156 
System generation, 151 
Traps to 4 & 10, 157 
DELETE 

Rubout filler character, 19 
Deleting windows, 75 
DEMOPA, example program, 161 
Detached jobs, 70 

Checking status of, S7 
Starting, S6 
.DEVICE, 152, 167 
Device allocation, 66 
Device handlers 
CI, 101 
CL, 101 
DM, 112 
DU, lis 
IB, 118 
LD, lis 
MU, 116 
VM, 116 
XL, 118 
DIBOL, 169 

Record locking, 170 
Record locking procedures, 81 
SEND statement, 170 
Support subroutines, 191 
DILOG DQ215, US 
Directory caching 

Dismounting a file structure, 41 
Dismounting all file structures, 42 
Mounting a file structure, 40 
Directory information 

EMT to obtain, 50 
Dismounting a file structure 
EMT to dismount all, 42 
EMT to dismount one, 41 
DL-11, 1 
DM handler, 112 
•DRxxx, 167 

DSPDAT, example program, 186 
DSPTI5, example program, 186 
DTR 

EMT to raise or lower, 62 
DU handler, 113 
DZ-11, 1 



CTRL-D breakpoints, 154 

Ekho control, 20 
EMT 

Differences, 167 

Table, 177 

TSX-Flus specific, 25 
Emulex SC02C, 113 
Error codes, 167 
Escape sequence 

Processing, 19 
Exclusive access to a file, 81 
Exclusive system control, 129 

Releeusing, 129 
Execution priority, 9 
.EXIT, 167 
Extended memory regions, 10 

.FETCH, 168 

Field width activation, 21 

Field width limit for TT input, 22 

File 

Block locking, 81 

Context, 70 

Creation time, 51 

Data caching, 91 

Directory information, 50 

Exclusive access, 81 

Opening for shared access, 81 

Protection modes, 81 

Shared access, 81 
FILEX, 170 
Fixed offsets, 7 
Fixed-high-priority 

Determining, 25 
Fixed- low-priority 

Determining, 25 
Floating point, 169 
Foreground programs 

See Real-time support. 
.FORK, 168 
FORTRAN 

I/O page mapping, 170 

Virtual arrays, 144, 170 

Global data areas, 145 

Global PLAS regions, 10 

Graphics 

CTRL-], 19 

.GTJB, 168 

.GTLIN, 168 

.GVAL, 168 

Checking I/O page mapping, 122 
Special TSX-Plus use, 25 

Hardware requirements, 1 
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High-efficiency terminal mode, 18, 19, 21, 33 
HOLD mode 

EJMT to specify for a file, 58 
.HRESET, 168 

I/O channels, 169, 171 
I/O page 

Accessing, 9, 121 

FORTRAN, 170 
IB handler, 113 

IBSRQ unsupported, 113 
IEEE handler 

see IB handler. 
IND 

.ASK directive, 170 
INI-E8, 169 
.INTEN, 168 
Interactive jobs 

Selecting dynamically, 60 
Interprogram communication, 93 

Checking for messages, 94 

Common memory areas, 145 

Completion routine, 97 

Nfessage channels, 93 

Sending a message, 93 

Vi^aiting for a message, 96 
Interrupt completion routine, 140 
Interrupt processing 

(Diagram), 136 
Interrupts 

Connecting to real-time jobs, 134 
Introduction, 1 

INTSVC, example program, 188 
lOABT parameter 

Needed for VTCOM, 102 

Job context 

Acquiring, 70 
Job mionitoring, 67 
Job nwmber 

Determining, 25 
Job priority 

Determining, 25 

Setting, 55, 138 
Job scheduling, 2 
Job status information, 47 
Job status word 

Non-wait TT I/O, 22 

Setting virtual flag with SETSIZ, 175 

Virtual- image flag, 9 
JSW 

See Job status word., 22 

KILL command, 38 
KILL EMT, 37 



LD 

Special functions, 118 
LD handler, 113 
Lead-in character, 17, 19 

Determining, 25 
License number 

Determining TSX-Plus, 25 
Line number 

Determining, 27 

Determining primary, 25 
Line-feed 

Echoing of, 22 

Ignored with tape mode, 22 
Lines 

Assigning to CL, 64 
LINK command 

/XM switch, 9 
Link map, 151 
Local named regions, 10 
.LOCK, 168 

Locking a job in memory, 180 
Logical disks 

determining status, 48 
Logical Disks 

Dismounting, 42 

EMT to dismount all LD's, 45 

Mounting, 78 
Logical subset disks 

EMT to dismount all, 42 
Lower-case character input, 20 

.MAP, 168 

Mapping to physical memory 

EMT for, 127 
Maximum priority 

Determining, 25 
Memory 

Using as pseudo-disk, 12 
Memory allocation 

EMT to control, 46 

Setting size in SAV file, 173 
MEMORY command, 47, 178 
Memory mapping, 7 
MEMSIZ parameter 

and VM handler, 116 
Message channels 

See Interprogram communication. 
Message communication 

See Interprogram communicati 
Messages 

Sending to another line, 35 
MicroPower/Pascal, 170 
Modification of shared files 

Checking for, 90 
MONITOR command, 159 
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Monitoring another job, 67 
MOUNT connmand, 40, 78 
Mounting a file structure, 40 
.MRKT, 168 
.MTPS, 168 
MU handler, 116 
Multi-terminal EMTs, 168 
.MWAIT, 168 

Named PLAS regions, 10 
NOHOLD mode 

EMT to specify for a file, 58 
Non-blocking .TTOUTR, 16 
Non-blocking .TTYIN, 16 
Non-interactive jobs 

Selecting dynamically, 60 
Non-wait TT I/O, 22 
Normal programs, 8 

Obtaining TSX-Plus system values, 25 
ODT 

See Debugger. 
ODT activation mode, 29 
Opening shared files, 81 
Overlaid programs, 171 

Paint character 

See Rubout filler character. 
PAR 7 mapping 

Determining, 25 

FORTRAN, 170 
.PEEK, 124, 168 
Performance monitor, 159 

Control EMTs, 161 

Displaying results, 160 

MONITOR command, 159 

Starting, 159, 161 
PHYADD, example program, 132 
Physical address calculation, 131 
Physical address space, 8 
Physical memory 

EMT to map to, 127 
PLAS support, 10 
.POKE, 124, 168 
Poke EMT, 125 
Primary line 

Determining, 25 
Printing windows 

EMT, 76 
Priorities, 9 
Priority level 

Setting, 55, 133 
Privilege 

EMT to determine or change, 57 

Re(!.i-time, 121 



PRIVIR parameter, 55, 134 
Process windows 

EMTs, 72 
Processor priority level 

Setting, 133 
Processor status word 

Debugger, 157 
Program controUed terminal options 

See Terminal c 
Program debugger, 151 
Program name 

EMT to get or change, 54 
Programmed Logical Address Space 

See PLAS support. 
Programmer number 

Determining, 25 
Project number 

Determining, 25 
.PROTECT, 144, 168 
Protected access to a file, 81 
PRTDE2, example program, 184 
PRTDEC, example program, 183 
PRTOCT, example program, 183 
PRTR50, example program, 184 
Pseudo-disk in memory, 12 
.PURGE 

Shared files and, 84 

.QSET, 168 

R command 

/DEBUG switch, 47 

/NONINTERACTIVE switch, 60 

/SINGLECHAR switch, 21 
R50ASC, example program, 185 
RADASC, example program, 189 
.RCVD, 168 

Read time-out value for TT inputs, 32 
Real-time, 121 

Accessing the I/O page, 121, 123, 127 

Adapting RT-11 programs, 144 

Completion routine, 140 

Device reset on exit, 132 

Interrupt connections, 134 

Locking a job in memory, 130 

Mapping to physical addresses, 127 

Physical address calculation, 131 

Poke EMT, 125 

Priority, 141 

Privilege, 121 

Suspending/resuming execution, 131 
Record locking, 81 

DIBOL, 170 

See Shared files. 
Redefining time-sharing lines, 3 
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Reentrant run-times 

See Shared run-time systems. 
Regions in extended memory, 10 
.RELEAS, 169 

Releasing exclusive system control, 129 
Requesting exclusive system control, 129 
Resident run-times 

See Shared run-time systems. 
Restrictions 

DM handler, 112 

IB handler, 113 

VM handler, 116 
Restrictions on .MAP EMT, 11 
Resuming windows, 76 
RK06/RK07 handler, 112 
RMON 

Real-time support consideration, 122 

Simulated, 7 

Simulated, 8 

SYSGEN options word, 27 
.RSUM, 131 
RTSORT, 70 

Rubout filler character, 19 
Run-time systems 

See Shared run-time systems. 

.SAVESTATUS 

Sh«u*ed files and, 84 
.SCCA, 169 

Scheduling a completion routine, 143 
Scheduling of jobs, 2 
.SDAT, 169 
.SDTTM, 169 
Selecting window, 75 
SEND 

DIBOL statement, 170 
Sending messages 

EMT for, 35 
Serial devices 

CL units, 3 
SET command 

TT TAPE, 22 

TT terminal-type, 46 
SETSIZ program, 47, 173 
Setting processor priority level, 133 
.SETTOP, 46, 169, 173 
.SFPA, 169 

Shared access to a file, 81 
Shared files, 81 

Checking for modification of, 90 

DIBOL, 170 

Opening, 81 

Protection modes, 82 

Saving channel status, 84 

Testing for locked blocks, 88 



Unlocking a block, 89 

Unlocking all locked blocks, 90 

Waiting for locked block, 86 
Shared run-time systems, 145 

Associating with job, 145 

Debugger, 156 

Mapping into job region, 11, 146 
Shared run-times 

Fast mapping, 147 
Simulated RMON, 7 

Access through page 7, 8 

Real-time support consideration, 122 
Single character activation, 15, 21, 156 
Special Chain Exit, 12 
Speed 

See terminal speed. 
SPFUN, 105 
.SPFUN, 169 

BYPASS, lis, 116 
.SPND, 131 
Spooled devices, 118 
Spooler 

Bypassing, 119 
Spooling 

CL device, 104 

Number of free spool blocks, 26 
.SRESET, 169 
Subprocess, 76 

determining job number, 28 

Disabling use of, 20 
Summaries of chapters, 3 
Suspending windows, 75 
Symbolic instruction decoding, 151 
.SYNCH, 169 
SYSGEN options word, 27 
SYSPRV privUege 

Determining, 25 
System device 

Determining, 25 
System generation parameter 

CLDEF, 102 

CLXTRA, 102 

MEMSIZ, 116 
System resource management, 2 
System values 

Obtaining, 25 

Tape mode, 22 
Terminal 

Determining type, 46 

Handler, 15 

Setting options, 59 

Setting speed, 61 
Terminal control, 15 

Break sentinel, S8 
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Character echoing, 20 

Checking for activation, S4 

Checking for input errors, SI 

Command file input, 21 

Defining activation characters, 20 

Determining input chars, pending, S2 

Dbabling subprocess use, 20 

Echo control, 20 

Field width activation, 21 

Field width limit, 22 

High-efficiency mode, 21, 38 

Line-feed echoing, 22 

Lower-case character input, 20 

Non-wait TT I/O, 22 

ODT activation mode, 29 

Read time-out value, 32 

Resetting activation characters, 21 

Rubout filler character, 19 

Single character activation, 21 

Tape mode, 22 

Transparency mode output, 20 

VT52 k VTIOO escape sequences, 19 
Time-out value for TT reads, 82 
Time-sharing lines 

Assigning to CL, 8, 64 
.TLOCK, 169 
TRANSF program, 102 
Transparency mode output, 20 
Trap to 10 

Debugger, 157 
Trap to 4 

Debugger, 157 
TSX-Plus 

Determining if under, 26 
TSX-Plus license number 

Determining, 25 
TSX-Plus version number 

Determining, 25 
TSXPM program, 159, 160 
TSXUCL 

File Size, 25 
TT/CL cross connection, 103 
.TTINR, 16, 169 
.TTOUTR, 16, 169 

Non-wait output, 22 
.TTYIN 

Non-wait input, 22 

Time-out value, 82 
.TTYOUT, 169 
.TWAIT, 169 

UCI, 12 

.UNLOCK, 169 

Unlocking a job from memory, 131 

Unnamed PLAS regions, 10 



.UNPROTECT, 169 

User command interface, 12 

User name 

Changing, 53 

Determining, 53 
USERTS, example program, 146 

Version number 

Determining, 25 
Virtual arrays 

FORTRAN, 170 

I/O page, 170 

PAR 7 mapping, 144 
Virtual memory, 7 
Virtual programs, 8 

Setting flag with SETSIZ, 175 
Virtual region mapping, 127 
Virtual to physical address, 8, 131 
Virtual windows, 11 
VM 

Handler, 12 

Initialising, 12 

SET BASE command, 12 
VM handler, 116 
VMS file transfer, 103 
VTIOO support, 19 
VT200 support, 19 
VT52 support, 19 
VTCOM 

Spooled CL unit, 119 
VTCOM program, 102 

Watchpoint 

Debugger, 151 
Window 

Creating, 72 

Deleting, 75 

EMTs, 72 

Printing, 76 

Resuming, 76 

Selecting, 75 

Suspending, 75 

XL handler, 118 



